ttsc 0.32.1 → 0.33.0

package/cmd/ttsc-cache/publisher_seal_test.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+  "crypto/sha256"
+  "encoding/hex"
+  "encoding/json"
+  "net/http"
+  "net/http/httptest"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "regexp"
+  "runtime"
+  "strings"
+  "testing"
+)
+
+// TestPublisherSeal verifies an actual recorded Go action through released-pack admission.
+//
+// Verifies: a publisher's full action and body can be sealed, transferred in bulk, and used by a relocated stock-Go consumer without compiling the package.
+// 1. Compile one package with the production helper recording into an empty overlay and retain Go's action graph and package receipts.
+// 2. Seal a release-pinned ZIP, serve it from loopback, and admit it into an independent consumer base.
+// 3. Build the same package from a different source root with a fresh Go cache, then compare archive bytes and compiler commands.
+//
+// @evidence contracts/testing.md#behavioral-verification The test executes the shipped helper's recording, sealing, preparation and protocol modes with stock Go, asserting a complete manifest digest, a real base hit and byte-identical archives.
+// @evidence contracts/testing.md#independent-expectations The literal package source and Go's own cold first-build compiler command establish a compile that the independent second cache must avoid; SHA-256 of each emitted archive establishes output equality.
+// @evidence contracts/testing.md#distinguishing-cases Distinct source, overlay, base and GOCACHE roots distinguish publisher reuse from an ordinary warm build; direct helper tests own malformed transport and protocol cases.
+// @evidence contracts/testing.md#execution-ownership This discoverable Go integration test builds a local helper and two private modules, serves one loopback pack, and removes all files through t.TempDir; no consumer install or external network is involved.
+func TestPublisherSeal(t *testing.T) {
+  if !supportedGoVersion.MatchString(runtime.Version()) {
+    t.Skip("publisher protocol 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)
+  }
+  root := filepath.Join(t.TempDir(), "publisher path with spaces")
+  if err := os.MkdirAll(root, 0700); err != nil {
+    t.Fatal(err)
+  }
+  helper := filepath.Join(root, "cache helper"+exeSuffix())
+  buildHelper := exec.Command(goBinary, "build", "-trimpath", "-o", helper, ".")
+  if output, err := buildHelper.CombinedOutput(); err != nil {
+    t.Fatalf("helper build: %v\n%s", err, output)
+  }
+  source := "package tiny\nfunc Value() string { return \"sealed action\" }\n"
+  makeModule := func(name string) string {
+    directory := filepath.Join(root, name)
+    if err := os.MkdirAll(directory, 0700); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.WriteFile(filepath.Join(directory, "go.mod"), []byte("module example.org/ttsc-cache-seal\n\ngo 1.26\n"), 0600); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.WriteFile(filepath.Join(directory, "tiny.go"), []byte(source), 0600); err != nil {
+      t.Fatal(err)
+    }
+    return directory
+  }
+  publisher := makeModule("publisher")
+  consumer := makeModule("consumer")
+  graph := filepath.Join(root, "actiongraph.json")
+  packages := filepath.Join(root, "packages.json")
+  list := exec.Command(goBinary, "list", "-deps", "-json", ".")
+  list.Dir = publisher
+  list.Env = append(os.Environ(), "CGO_ENABLED=0", "GOFLAGS=", "GOWORK=off", "GOPROXY=off", "GOSUMDB=off", "GOTOOLCHAIN=local", "GOCACHEPROG=")
+  listOutput, err := list.CombinedOutput()
+  if err != nil {
+    t.Fatalf("publisher package receipts: %v\n%s", err, listOutput)
+  }
+  if err := os.WriteFile(packages, listOutput, 0600); err != nil {
+    t.Fatal(err)
+  }
+  serverRoot := filepath.Join(root, "sealed")
+  server := httptest.NewServer(http.FileServer(http.Dir(serverRoot)))
+  defer server.Close()
+  compile := regexp.MustCompile(`(?m)[/\\]compile(?:\.exe)?["']?\s`)
+  build := func(directory, cache, program, archive, graphPath string) (string, int) {
+    if err := os.MkdirAll(cache, 0700); err != nil {
+      t.Fatal(err)
+    }
+    args := []string{"build", "-trimpath", "-x", "-o", archive}
+    if graphPath != "" {
+      args = append(args, "-debug-actiongraph="+graphPath)
+    }
+    args = append(args, ".")
+    command := exec.Command(goBinary, args...)
+    command.Dir = directory
+    command.Env = append(os.Environ(), "CGO_ENABLED=0", "GOFLAGS=", "GOWORK=off", "GOPROXY=off", "GOSUMDB=off", "GOTOOLCHAIN=local", "GOCACHE="+cache, "GOCACHEPROG="+program)
+    output, err := command.CombinedOutput()
+    if err != nil {
+      t.Fatalf("stock Go build: %v\n%s", err, output)
+    }
+    body, err := os.ReadFile(archive)
+    if err != nil {
+      t.Fatal(err)
+    }
+    sum := sha256.Sum256(body)
+    return hex.EncodeToString(sum[:]), len(compile.FindAll(output, -1))
+  }
+  overlay := filepath.Join(root, "publisher overlay")
+  firstProgram := quoteGoCacheArgument(helper) + " -root " + quoteGoCacheArgument(overlay)
+  firstHash, firstCompiles := build(publisher, filepath.Join(root, "publisher go cache"), firstProgram, filepath.Join(root, "first.a"), graph)
+  if firstCompiles == 0 {
+    t.Fatal("publisher did not compile the package")
+  }
+  seal := exec.Command(helper, "-seal", "-root", overlay, "-go", goBinary, "-actiongraph", graph, "-packages", packages, "-release", "0.32.1", "-source-commit", strings.Repeat("a", 40), "-pack-url-base", server.URL, "-pack-name", "tiny", "-out", serverRoot)
+  seal.Env = append(os.Environ(), "CGO_ENABLED=0", "GOFLAGS=", "GOWORK=off", "GOPROXY=off", "GOSUMDB=off", "GOTOOLCHAIN=local")
+  output, err := seal.CombinedOutput()
+  if err != nil {
+    t.Fatalf("seal recorded actions: %v\n%s", err, output)
+  }
+  var sealed struct {
+    ManifestSHA256 string `json:"manifestSHA256"`
+    Actions        int    `json:"actions"`
+  }
+  if err := json.Unmarshal(output, &sealed); err != nil || sealed.Actions == 0 || len(sealed.ManifestSHA256) != 64 {
+    t.Fatalf("invalid publisher seal receipt: %s %v", output, err)
+  }
+  manifest := filepath.Join(serverRoot, "manifest.json")
+  base := filepath.Join(root, "independent consumer base")
+  prepare := exec.Command(helper, "-root", base, "-manifest", manifest, "-manifest-sha256", sealed.ManifestSHA256, "-prepare", "-packs", "tiny")
+  if output, err := prepare.CombinedOutput(); err != nil {
+    t.Fatalf("prepare sealed pack: %v\n%s", err, output)
+  }
+  secondProgram := quoteGoCacheArgument(helper) + " -root " + quoteGoCacheArgument(base) + " -manifest " + quoteGoCacheArgument(manifest) + " -manifest-sha256 " + sealed.ManifestSHA256
+  secondHash, secondCompiles := build(consumer, filepath.Join(root, "consumer go cache"), secondProgram, filepath.Join(root, "second.a"), "")
+  if secondCompiles != 0 || firstHash != secondHash {
+    t.Fatalf("sealed publisher package was not reused: compiles=%d/%d hashes=%s/%s", firstCompiles, secondCompiles, firstHash, secondHash)
+  }
+}

package/cmd/ttsc-cache/seal.go

@@ -0,0 +1,427 @@
+package main
+
+import (
+  "archive/zip"
+  "compress/flate"
+  "crypto/sha256"
+  "encoding/base64"
+  "encoding/hex"
+  "encoding/json"
+  "errors"
+  "fmt"
+  "io"
+  "os"
+  "path/filepath"
+  "sort"
+  "strings"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/packageartifacts"
+)
+
+type sealOptions struct {
+  root, goBinary, actionGraph, packages, release, sourceCommit string
+  packURLBase, packName, outputDir                             string
+}
+
+type graphAction struct {
+  ID       int      `json:"ID"`
+  Mode     string   `json:"Mode"`
+  Package  string   `json:"Package"`
+  Deps     []int    `json:"Deps"`
+  ActionID string   `json:"ActionID"`
+  Cmd      []string `json:"Cmd"`
+}
+
+type packageReceipt struct {
+  ImportPath string
+  Dir        string
+  GoFiles    []string
+  CgoFiles   []string
+  SFiles     []string
+  EmbedFiles []string
+  Module     *struct {
+    Path    string
+    Version string
+    Main    bool
+    Replace *struct {
+      Path    string
+      Version string
+    }
+  }
+}
+
+// SealRecordedActions joins Go's displayed build actions to the full action and
+// output IDs recorded by its cache client. Package receipts annotate those IDs;
+// they never generate or replace a Go cache key. A release package must pin the
+// printed manifest digest before a consumer may trust the result.
+//
+// @evidence contracts/common.md#principled-implementation Only full recorded actions with verified local bodies are sealed; a same-workspace Go action graph and package receipts add diagnostics, while the release pins the resulting manifest digest.
+// @evidence contracts/common.md#clear-and-simple-design One publisher command reads bounded Go receipts, verifies body associations, writes one deterministic pack and authenticates its complete manifest before reporting the digest.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A displayed action prefix is joined uniquely to a full recorded key; package names and source hashes cannot manufacture identities or resolve a conflict.
+// @evidence contracts/common.md#meaningful-documentation The contract names the release trust step and separates diagnostic receipts from Go's authoritative keys.
+// @evidence contracts/portability.md#os-neutral-implementation Go path and archive APIs process native publisher paths, while transport names use slash-separated ZIP entries independent of the publisher OS.
+// @evidence contracts/performance.md#efficient-algorithms Each selected package body is streamed once into a level-one ZIP and hashed; action joins use maps rather than comparing every graph node with every recorded action.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Publisher sealing is an explicit one-shot release operation and does not memoize mutable source or tool observations.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Receipt/action files have byte caps, package source reads are streamed, body handles close after each entry, and failed staging files are removed; the finished pack remains with the publisher output owner.
+func SealRecordedActions(opts sealOptions) error {
+  if !filepath.IsAbs(opts.root) || !filepath.IsAbs(opts.outputDir) || !filepath.IsAbs(opts.actionGraph) || !filepath.IsAbs(opts.packages) || !validPackName(opts.packName) {
+    return errors.New("publisher paths must be absolute and pack name must be safe")
+  }
+  tuple, err := readGoTuple(opts.goBinary)
+  if err != nil {
+    return err
+  }
+  graphRaw, err := readBoundedFile(opts.actionGraph, 16<<20)
+  if err != nil {
+    return err
+  }
+  var graph []graphAction
+  if err := json.Unmarshal(graphRaw, &graph); err != nil {
+    return fmt.Errorf("decode Go action graph: %w", err)
+  }
+  if len(graph) == 0 || len(graph) > 100000 {
+    return errors.New("Go action graph exceeds publisher policy")
+  }
+  receipts, err := readPackageReceipts(opts.packages)
+  if err != nil {
+    return err
+  }
+  store, err := openArtifactStore(opts.root, nil)
+  if err != nil {
+    return err
+  }
+  defer store.close()
+  recorded, err := readRecordedMappings(store)
+  if err != nil {
+    return err
+  }
+  byShort := make(map[string]string, len(recorded))
+  for actionID := range recorded {
+    bytes, _ := hex.DecodeString(actionID)
+    short := base64.RawURLEncoding.EncodeToString(bytes[:15])
+    if previous := byShort[short]; previous != "" && previous != actionID {
+      return fmt.Errorf("ambiguous Go action prefix %s", short)
+    }
+    byShort[short] = actionID
+  }
+  selected := make(map[int]packageartifacts.Action)
+  outputs := make(map[string]mapping)
+  for _, node := range graph {
+    if node.Mode != "build" || node.ActionID == "" {
+      continue
+    }
+    fullID := byShort[node.ActionID]
+    value, exists := recorded[fullID]
+    if !exists || node.Package == "" {
+      return fmt.Errorf("Go build action %s has no recorded full body", node.Package)
+    }
+    receipt, exists := receipts[node.Package]
+    if !exists {
+      return fmt.Errorf("Go build action %s has no package receipt", node.Package)
+    }
+    sourceHash, err := hashSelectedSources(receipt)
+    if err != nil {
+      return fmt.Errorf("package %s sources: %w", node.Package, err)
+    }
+    command, _ := json.Marshal(node.Cmd)
+    commandHash := sha256.Sum256(command)
+    role, modulePath, moduleVersion := receiptRole(receipt, tuple.GoVersion)
+    selected[node.ID] = packageartifacts.Action{
+      ActionID: fullID, OutputID: value.OutputID, BodySHA256: value.OutputID,
+      BodyLength: value.Size, Pack: opts.packName, Kind: "archive",
+      PackagePath: node.Package, ModulePath: modulePath, ModuleVersion: moduleVersion,
+      ModuleRole: role, SelectedSourceSHA: sourceHash,
+      CommandSHA256: hex.EncodeToString(commandHash[:]), DirectInputs: []string{},
+    }
+    if previous, exists := outputs[value.OutputID]; exists && previous.Size != value.Size {
+      return errors.New("recorded output has conflicting lengths")
+    }
+    outputs[value.OutputID] = value
+  }
+  if len(selected) == 0 {
+    return errors.New("no recorded package actions were selected")
+  }
+  manifest := packageartifacts.Manifest{
+    Schema: 1, Release: opts.release, SourceCommit: opts.sourceCommit,
+    Tuple: tuple, GraphSHA256: digestBytes(graphRaw), Actions: make([]packageartifacts.Action, 0, len(selected)),
+  }
+  for _, node := range graph {
+    action, exists := selected[node.ID]
+    if !exists {
+      continue
+    }
+    for _, dependency := range node.Deps {
+      if input, exists := selected[dependency]; exists {
+        action.DirectInputs = append(action.DirectInputs, input.OutputID)
+      }
+    }
+    sort.Strings(action.DirectInputs)
+    manifest.Actions = append(manifest.Actions, action)
+  }
+  sort.Slice(manifest.Actions, func(i, j int) bool { return manifest.Actions[i].ActionID < manifest.Actions[j].ActionID })
+  if err := os.MkdirAll(opts.outputDir, 0700); err != nil {
+    return err
+  }
+  stage, err := os.CreateTemp(opts.outputDir, ".ttsc-pack-*.zip")
+  if err != nil {
+    return err
+  }
+  defer os.Remove(stage.Name())
+  writer := zip.NewWriter(stage)
+  writer.RegisterCompressor(zip.Deflate, func(destination io.Writer) (io.WriteCloser, error) {
+    return flate.NewWriter(destination, flate.BestSpeed)
+  })
+  ids := make([]string, 0, len(outputs))
+  for outputID := range outputs {
+    ids = append(ids, outputID)
+  }
+  sort.Strings(ids)
+  var decodedBytes int64
+  for _, outputID := range ids {
+    value := outputs[outputID]
+    location := filepath.ToSlash(filepath.Join("overlay", "bodies", outputID))
+    body, err := store.root.Open(location)
+    if err != nil {
+      writer.Close()
+      stage.Close()
+      return err
+    }
+    info, err := body.Stat()
+    if err != nil || !info.Mode().IsRegular() || info.Size() != value.Size {
+      body.Close()
+      writer.Close()
+      stage.Close()
+      return fmt.Errorf("recorded body %s changed", outputID)
+    }
+    entry, err := writer.Create("bodies/" + outputID)
+    if err != nil {
+      body.Close()
+      writer.Close()
+      stage.Close()
+      return err
+    }
+    hash := sha256.New()
+    count, copyErr := io.CopyN(io.MultiWriter(entry, hash), body, value.Size)
+    closeErr := body.Close()
+    if copyErr != nil || closeErr != nil || count != value.Size || hex.EncodeToString(hash.Sum(nil)) != outputID {
+      writer.Close()
+      stage.Close()
+      return fmt.Errorf("recorded body %s failed verification: %w", outputID, errors.Join(copyErr, closeErr))
+    }
+    decodedBytes += count
+    if decodedBytes > packageartifacts.MaxPackDecodedBytes {
+      writer.Close()
+      stage.Close()
+      return errors.New("pack exceeds decoded byte policy")
+    }
+  }
+  if err := writer.Close(); err != nil {
+    stage.Close()
+    return err
+  }
+  if err := stage.Sync(); err != nil {
+    stage.Close()
+    return err
+  }
+  if err := stage.Close(); err != nil {
+    return err
+  }
+  packRaw, err := hashFile(stage.Name(), packageartifacts.MaxPackBytes)
+  if err != nil {
+    return err
+  }
+  packFile := opts.packName + "-" + packRaw.digest + ".zip"
+  manifest.Packs = []packageartifacts.Pack{{
+    Name: opts.packName, URL: strings.TrimRight(opts.packURLBase, "/") + "/" + packFile,
+    SHA256: packRaw.digest, Length: packRaw.length, DecodedBytes: decodedBytes, FileCount: len(ids),
+  }}
+  manifestRaw, err := json.MarshalIndent(manifest, "", "  ")
+  if err != nil {
+    return err
+  }
+  manifestRaw = append(manifestRaw, '\n')
+  manifestDigest := digestBytes(manifestRaw)
+  if _, err := packageartifacts.ParseTrustedManifest(manifestRaw, manifestDigest); err != nil {
+    return fmt.Errorf("publisher manifest rejected: %w", err)
+  }
+  finalPack := filepath.Join(opts.outputDir, packFile)
+  if err := os.Link(stage.Name(), finalPack); err != nil {
+    if !errors.Is(err, os.ErrExist) {
+      return err
+    }
+    existing, hashErr := hashFile(finalPack, packageartifacts.MaxPackBytes)
+    if hashErr != nil || existing != packRaw {
+      return errors.New("existing publisher pack differs from sealed bytes")
+    }
+  }
+  manifestFile, err := os.OpenFile(filepath.Join(opts.outputDir, "manifest.json"), os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+  if err != nil {
+    return err
+  }
+  _, writeErr := manifestFile.Write(manifestRaw)
+  syncErr := manifestFile.Sync()
+  closeErr := manifestFile.Close()
+  if writeErr != nil || syncErr != nil || closeErr != nil {
+    return errors.Join(writeErr, syncErr, closeErr)
+  }
+  return json.NewEncoder(os.Stdout).Encode(struct {
+    ManifestSHA256  string `json:"manifestSHA256"`
+    Pack            string `json:"pack"`
+    Actions         int    `json:"actions"`
+    DecodedBytes    int64  `json:"decodedBytes"`
+    CompressedBytes int64  `json:"compressedBytes"`
+  }{manifestDigest, packFile, len(manifest.Actions), decodedBytes, packRaw.length})
+}
+
+func readRecordedMappings(store *artifactStore) (map[string]mapping, error) {
+  directory, err := store.root.Open("overlay/actions")
+  if err != nil {
+    return nil, err
+  }
+  defer directory.Close()
+  entries, err := directory.ReadDir(-1)
+  if err != nil {
+    return nil, err
+  }
+  if len(entries) > 100000 {
+    return nil, errors.New("too many publisher actions")
+  }
+  result := make(map[string]mapping, len(entries))
+  for _, entry := range entries {
+    if !validID(entry.Name()) || !entry.Type().IsRegular() {
+      return nil, errors.New("publisher action index contains an unsafe entry")
+    }
+    index, err := store.root.Open(filepath.ToSlash(filepath.Join("overlay", "actions", entry.Name())))
+    if err != nil {
+      return nil, err
+    }
+    raw, readErr := io.ReadAll(io.LimitReader(index, 257))
+    closeErr := index.Close()
+    if readErr != nil || closeErr != nil || len(raw) > 256 {
+      return nil, errors.New("publisher action index is unreadable or too large")
+    }
+    var value mapping
+    if err := json.Unmarshal(raw, &value); err != nil || !validID(value.OutputID) || value.Size < 0 || value.Size > 512<<20 {
+      return nil, errors.New("publisher action index is invalid")
+    }
+    result[entry.Name()] = value
+  }
+  return result, nil
+}
+
+func readPackageReceipts(filename string) (map[string]packageReceipt, error) {
+  file, err := os.Open(filename)
+  if err != nil {
+    return nil, err
+  }
+  defer file.Close()
+  info, err := file.Stat()
+  if err != nil || !info.Mode().IsRegular() || info.Size() > 256<<20 {
+    return nil, errors.New("package receipts exceed publisher policy")
+  }
+  decoder := json.NewDecoder(io.LimitReader(file, (256<<20)+1))
+  result := make(map[string]packageReceipt)
+  for {
+    var receipt packageReceipt
+    if err := decoder.Decode(&receipt); err == io.EOF {
+      break
+    } else if err != nil {
+      return nil, fmt.Errorf("decode package receipt: %w", err)
+    }
+    if receipt.ImportPath == "" || receipt.Dir == "" {
+      return nil, errors.New("incomplete package receipt")
+    }
+    if _, exists := result[receipt.ImportPath]; exists {
+      return nil, errors.New("duplicate package receipt")
+    }
+    result[receipt.ImportPath] = receipt
+    if len(result) > 100000 {
+      return nil, errors.New("too many package receipts")
+    }
+  }
+  return result, nil
+}
+
+func hashSelectedSources(receipt packageReceipt) (string, error) {
+  names := append(append(append([]string{}, receipt.GoFiles...), receipt.CgoFiles...), receipt.SFiles...)
+  names = append(names, receipt.EmbedFiles...)
+  sort.Strings(names)
+  hash := sha256.New()
+  for _, name := range names {
+    if filepath.IsAbs(name) || name == ".." || strings.HasPrefix(name, ".."+string(filepath.Separator)) {
+      return "", errors.New("selected source escaped package directory")
+    }
+    file, err := os.Open(filepath.Join(receipt.Dir, name))
+    if err != nil {
+      return "", err
+    }
+    _, _ = fmt.Fprintf(hash, "%d:%s\n", len(name), filepath.ToSlash(name))
+    count, copyErr := io.Copy(hash, io.LimitReader(file, (128<<20)+1))
+    closeErr := file.Close()
+    if copyErr != nil || closeErr != nil || count > 128<<20 {
+      return "", errors.New("selected source is unreadable or too large")
+    }
+    _, _ = fmt.Fprintf(hash, "\n%d\n", count)
+  }
+  return hex.EncodeToString(hash.Sum(nil)), nil
+}
+
+func receiptRole(receipt packageReceipt, goVersion string) (string, string, string) {
+  if receipt.Module == nil {
+    return "standard", "std", goVersion
+  }
+  version := receipt.Module.Version
+  if receipt.Module.Replace != nil {
+    version = receipt.Module.Replace.Version
+  }
+  if receipt.Module.Main {
+    return "main", receipt.Module.Path, version
+  }
+  return "dependency", receipt.Module.Path, version
+}
+
+func readBoundedFile(filename string, limit int64) ([]byte, error) {
+  file, err := os.Open(filename)
+  if err != nil {
+    return nil, err
+  }
+  defer file.Close()
+  info, err := file.Stat()
+  if err != nil || !info.Mode().IsRegular() || info.Size() > limit {
+    return nil, errors.New("publisher input exceeds byte policy")
+  }
+  return io.ReadAll(io.LimitReader(file, limit+1))
+}
+
+type fileDigest struct {
+  digest string
+  length int64
+}
+
+func hashFile(filename string, limit int64) (fileDigest, error) {
+  file, err := os.Open(filename)
+  if err != nil {
+    return fileDigest{}, err
+  }
+  defer file.Close()
+  hash := sha256.New()
+  count, err := io.Copy(hash, io.LimitReader(file, limit+1))
+  if err != nil || count > limit {
+    return fileDigest{}, errors.New("publisher pack exceeds compressed byte policy")
+  }
+  return fileDigest{hex.EncodeToString(hash.Sum(nil)), count}, nil
+}
+
+func digestBytes(value []byte) string { sum := sha256.Sum256(value); return hex.EncodeToString(sum[:]) }
+
+func validPackName(value string) bool {
+  if value == "" || len(value) > 80 {
+    return false
+  }
+  for _, char := range value {
+    if !strings.ContainsRune("abcdefghijklmnopqrstuvwxyz0123456789-", char) {
+      return false
+    }
+  }
+  return true
+}

package/cmd/ttsc-cache/stock_go_failure_test.go

@@ -0,0 +1,94 @@
+package main
+
+import (
+  "context"
+  "errors"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "runtime"
+  "strings"
+  "testing"
+  "time"
+)
+
+// TestStockGoCacheFailures verifies the real Go client's response to an already-started bad helper.
+//
+// Verifies: a malformed response and premature helper exit fail the Go build promptly and do not silently replay it against a local cache.
+// 1. Build a small helper that advertises the protocol, then emits malformed JSON or exits.
+// 2. Run stock Go against each mode with a fresh local cache and a fixed failure deadline.
+// 3. Require an identified cache-helper failure, no output archive, and no deadline expiry.
+//
+// @evidence contracts/testing.md#behavioral-verification Runs stock go build with GOCACHEPROG pointing to a deliberately broken executable and checks its process result and missing output.
+// @evidence contracts/testing.md#independent-expectations The stock Go client owns the helper failure contract: invalid JSON or EOF after valid startup cannot represent an action miss, so the build must fail without producing an archive.
+// @evidence contracts/testing.md#distinguishing-cases Covers malformed response and premature exit after valid capabilities; the production helper's valid protocol, hit and miss cases belong to TestStockGoCacheClient and TestCacheProtocol.
+// @evidence contracts/testing.md#execution-ownership This narrow Go subprocess test uses a temporary helper and tiny local module; it never installs a consumer or runs the product E2E suite.
+func TestStockGoCacheFailures(t *testing.T) {
+  if !supportedGoVersion.MatchString(runtime.Version()) {
+    t.Skip("the helper protocol requires a stock Go 1.26 patch release")
+  }
+  root := t.TempDir()
+  helperSource := filepath.Join(root, "broken-helper.go")
+  source := `package main
+import (
+  "bufio"
+  "fmt"
+  "os"
+)
+func main() {
+  fmt.Println("{\"ID\":0,\"KnownCommands\":[\"get\",\"put\",\"close\"]}")
+  if _, err := bufio.NewReader(os.Stdin).ReadBytes('\n'); err != nil {
+    return
+  }
+  if os.Getenv("TTSC_BAD_HELPER_MODE") == "malformed" {
+    fmt.Println("{broken")
+  }
+}
+`
+  if err := os.WriteFile(helperSource, []byte(source), 0600); err != nil {
+    t.Fatal(err)
+  }
+  helper := filepath.Join(root, "broken helper"+exeSuffix())
+  compile := exec.Command("go", "build", "-o", helper, helperSource)
+  compile.Env = append(os.Environ(), "GOCACHEPROG=", "GOTOOLCHAIN=local")
+  if output, err := compile.CombinedOutput(); err != nil {
+    t.Fatalf("building failing cache helper: %v\n%s", err, output)
+  }
+  module := filepath.Join(root, "client")
+  if err := os.MkdirAll(module, 0700); err != nil {
+    t.Fatal(err)
+  }
+  for name, body := range map[string]string{
+    "go.mod":  "module example.org/broken-cache-client\n\ngo 1.26\n",
+    "tiny.go": "package tiny\nfunc Value() string { return \"stock Go\" }\n",
+  } {
+    if err := os.WriteFile(filepath.Join(module, name), []byte(body), 0600); err != nil {
+      t.Fatal(err)
+    }
+  }
+  for _, mode := range []string{"malformed", "premature"} {
+    t.Run(mode, func(t *testing.T) {
+      cache := filepath.Join(root, "cache-"+mode)
+      if err := os.MkdirAll(cache, 0700); err != nil {
+        t.Fatal(err)
+      }
+      archive := filepath.Join(root, "archive-"+mode+".a")
+      context, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+      defer cancel()
+      build := exec.CommandContext(context, "go", "build", "-trimpath", "-o", archive, ".")
+      build.Dir = module
+      build.Env = append(os.Environ(),
+        "CGO_ENABLED=0", "GOFLAGS=", "GOWORK=off", "GOPROXY=off", "GOSUMDB=off", "GOTOOLCHAIN=local",
+        "GOCACHE="+cache, "GOCACHEPROG="+quoteGoCacheArgument(helper), "TTSC_BAD_HELPER_MODE="+mode,
+      )
+      output, err := build.CombinedOutput()
+      expected := map[string]string{"malformed": "invalid character", "premature": "exited pre-Close"}[mode]
+      if err == nil || context.Err() != nil || !strings.Contains(string(output), "GOCACHEPROG") || !strings.Contains(string(output), expected) {
+        t.Fatalf("stock Go did not fail promptly at the helper boundary: error=%v deadline=%v output=%s", err, context.Err(), output)
+      }
+      if _, err := os.Stat(archive); !errors.Is(err, os.ErrNotExist) {
+        t.Fatalf("stock Go produced an archive after a helper failure: %v", err)
+      }
+    })
+  }
+}