ttsc 0.32.1 → 0.33.0

package/driver/rewrite.go

@@ -157,10 +157,13 @@ func (p *Program) EmitAll(rs *RewriteSet, writeFile shimcompiler.WriteFile) (*sh
 // is the standard place to carry per-file cursors or an output map), so ttsc
 // owns the serialization rather than pushing goroutine-safety onto every
 // plugin author. See the emit-concurrency contract in the plugin docs.
+// A watch-owned writer may leave an already identical file in place; that
+// successful output remains in EmittedFiles. Rejected outDir paths are marked
+// skipped and do not appear there.
 //
 // @evidence contracts/common.md#principled-implementation Native emission honors linked program hooks, compiler incremental-output policy, and output containment while omitting only ttsc text rewrites.
 // @evidence contracts/common.md#clear-and-simple-design One serialized writer callback wraps the compiler emit owner and shared diagnostic conversion.
-// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler emission is not patched or replaced with expected-output text; skipped writes are marked for accurate emitted-file reporting.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler emission is not patched or replaced with expected-output text; rejected outDir writes are marked skipped, while identical existing watch outputs remain successful emitted files.
 // @evidence contracts/common.md#meaningful-documentation Native prose distinguishes raw output and guaranteed callback serialization following the documentation skill.
 // @evidence contracts/portability.md#os-neutral-implementation Native containment resolves compiler paths with its case policy, and DefaultWriteFile uses native filesystem APIs.
 // @evidence contracts/performance.md#efficient-algorithms Native generation processes the current program and emitted text; serialized callbacks add lexical path-containment and default filesystem or arbitrary caller-writer costs. Result diagnostics require conversion. Native threading policy remains selected by the loaded program, with no measured claim that callback serialization is inexpensive.
@@ -185,8 +188,8 @@ func (p *Program) EmitAllRaw(writeFile shimcompiler.WriteFile) (*shimcompiler.Em
     wfMu.Lock()
     defer wfMu.Unlock()
     if p.outputEscapesOutDir(fileName) {
-      // Marking the write skipped keeps the file out of EmitResult.EmittedFiles,
-      // so callers reporting emitted counts don't include phantom outputs.
+      // Marking a rejected path skipped keeps it out of EmittedFiles. An
+      // existing identical output is still an emitted result and stays listed.
       if data != nil {
         data.SkippedDtsWrite = true
       }
@@ -243,8 +246,8 @@ func (p *Program) emit(rs *RewriteSet, target *ast.SourceFile, writeFile shimcom
     wfMu.Lock()
     defer wfMu.Unlock()
     if p.outputEscapesOutDir(fileName) {
-      // See EmitAllRaw: mark the write skipped so EmitResult.EmittedFiles
-      // reflects only files actually written.
+      // See EmitAllRaw: rejected paths are absent from EmittedFiles, while an
+      // existing identical watch output remains a successful result.
       if data != nil {
         data.SkippedDtsWrite = true
       }
@@ -316,19 +319,25 @@ func (p *Program) emitsBuildInfo() bool {
 }
 
 // DefaultWriteFile is the default disk writer used when EmitAll's caller does not
-// supply a custom WriteFile callback. Existing files are truncated; a failed
-// write can leave partial output. Requested creation modes are subject to the
-// native platform and umask, and do not replace existing file permissions.
+// supply a custom WriteFile callback. Existing files are normally truncated; a
+// watch child setting TTSC_WATCH_WRITE_IF_CHANGED=1 preserves byte-identical
+// regular output files instead. A failed write can leave partial output.
+// Requested creation modes are subject to the native platform and umask, and
+// do not replace existing file permissions.
 //
-// @evidence contracts/common.md#principled-implementation Parent directories are created before the output is written, and native errors remain visible to emit callers.
-// @evidence contracts/common.md#clear-and-simple-design One directory-creation step precedes one file write.
-// @evidence contracts/common.md#prohibited-implementation-shortcuts The writer uses actual requested filenames without suppressing filesystem failures or relying on shell commands.
-// @evidence contracts/common.md#meaningful-documentation Native prose identifies the default callback role following the documentation skill.
-// @evidence contracts/portability.md#os-neutral-implementation filepath.Dir, os.MkdirAll, and os.WriteFile supply OS-neutral native operations without separator or command assumptions.
-// @evidence contracts/performance.md#efficient-algorithms Native parent creation can walk missing ancestors and query existing entries; path length/depth and output bytes drive delegated work. The text-to-byte conversion and file write process the supplied output without a directory enumeration or intermediate output collection.
-// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each emit write is requested independently; this writer owns no reuse coordinator.
-// @evidence contracts/performance.md#bound-retention-and-release-resources os.WriteFile opens one output handle and attempts its closure after the write, including write failure; open failure acquires no handle. The adapter retains no handle or historical output buffer after returning, but created directories and partial or completed files remain on disk without rollback.
+// @evidence contracts/common.md#principled-implementation The watch-only opt-in compares an existing writable regular output before deciding whether native writing is needed; all other writes use the original directory and file operations.
+// @evidence contracts/common.md#clear-and-simple-design One opt-in decision selects the unchanged-output check or the original writer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Native file identity and bytes decide whether to skip; unknown state falls back to the original writer and its errors.
+// @evidence contracts/common.md#meaningful-documentation Native prose states normal truncation, watch opt-in, partial failure and permission behavior.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Dir, os.MkdirAll and os.WriteFile preserve native path and permission behavior; the optional check uses native file identity rather than path spelling.
+// @evidence contracts/performance.md#efficient-algorithms Normal writes retain one directory creation and file write. Watch writes add metadata and streamed comparison of up to the existing output size, then write only when content differs or safe comparison fails; no prior-output cache is retained.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each emit write is requested independently; this writer owns no cross-emit reuse coordinator.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The optional comparison closes its one read/write handle before return or fallback; os.WriteFile owns and closes the later write handle. No output buffer or handle survives this call, while created directories and partial or completed files remain on disk.
 func DefaultWriteFile(fileName, text string) error {
+  return writeFileWithWatchMode(fileName, text, os.Getenv("TTSC_WATCH_WRITE_IF_CHANGED") == "1")
+}
+
+func defaultWriteFile(fileName, text string) error {
   if dir := filepath.Dir(fileName); dir != "" {
     if err := os.MkdirAll(dir, 0o755); err != nil {
       return err

package/driver/write_file_if_changed.go

@@ -0,0 +1,69 @@
+package driver
+
+import (
+  "bytes"
+  "io"
+  "os"
+)
+
+// writeFileWithWatchMode preserves an unchanged regular output only for a
+// watch-owned write. A failed comparison does not replace the default writer's
+// errors or its behavior for symlinks, special files and absent parents.
+func writeFileWithWatchMode(fileName, text string, watch bool) error {
+  if watch && unchangedRegularOutput(fileName, text) {
+    return nil
+  }
+  return defaultWriteFile(fileName, text)
+}
+
+// unchangedRegularOutput compares through a read/write descriptor so a file
+// that the normal writer cannot open for writing is never treated as success.
+// Identity and metadata checks reject a file replaced during the comparison;
+// a later independent filesystem mutation remains a caller-visible race.
+func unchangedRegularOutput(fileName, text string) bool {
+  before, err := os.Lstat(fileName)
+  if err != nil || !before.Mode().IsRegular() || before.Size() != int64(len(text)) {
+    return false
+  }
+  file, err := os.OpenFile(fileName, os.O_RDWR, 0)
+  if err != nil {
+    return false
+  }
+  same := matchesOpenRegularOutput(file, fileName, before, text)
+  if err := file.Close(); err != nil {
+    return false
+  }
+  return same
+}
+
+func matchesOpenRegularOutput(file *os.File, fileName string, before os.FileInfo, text string) bool {
+  opened, err := file.Stat()
+  if err != nil || !opened.Mode().IsRegular() || !os.SameFile(before, opened) || opened.Size() != int64(len(text)) {
+    return false
+  }
+  var buffer [32 * 1024]byte
+  for offset := 0; offset < len(text); {
+    count := min(len(buffer), len(text)-offset)
+    read, err := io.ReadFull(file, buffer[:count])
+    if err != nil || !bytes.Equal(buffer[:read], []byte(text[offset:offset+read])) {
+      return false
+    }
+    offset += read
+  }
+  if _, err := file.Read(buffer[:1]); err != io.EOF {
+    return false
+  }
+  afterOpen, err := file.Stat()
+  if err != nil {
+    return false
+  }
+  afterPath, err := os.Lstat(fileName)
+  if err != nil {
+    return false
+  }
+  return afterPath.Mode().IsRegular() &&
+    os.SameFile(opened, afterOpen) && os.SameFile(opened, afterPath) &&
+    afterOpen.Mode() == opened.Mode() && afterPath.Mode() == opened.Mode() &&
+    afterOpen.Size() == opened.Size() && afterPath.Size() == opened.Size() &&
+    afterOpen.ModTime().Equal(opened.ModTime()) && afterPath.ModTime().Equal(opened.ModTime())
+}

package/driver/write_file_if_changed_test.go

@@ -0,0 +1,148 @@
+package driver
+
+import (
+  "os"
+  "path/filepath"
+  "testing"
+  "time"
+)
+
+// TestWriteFileWithWatchMode verifies the watch writer's disk effects and
+// fallback against the ordinary writer.
+//
+// Verifies that only an existing, byte-identical regular file is preserved.
+// 1. Write missing and changed outputs in watch mode and read their bytes.
+// 2. Mark identical outputs with an old timestamp and compare watch and normal writes.
+// 3. Exercise blocked parents, read-only outputs and a symlink against normal writes.
+//
+// @evidence contracts/testing.md#behavioral-verification The direct disk writer creates and changes real files, preserves an unchanged watch output's timestamp and mode, and still reports native write failures.
+// @evidence contracts/testing.md#independent-expectations Authored literal bytes and a fixed old timestamp establish the expected output independently of the writer; normal mode on an equivalent file is the permission/error reference.
+// @evidence contracts/testing.md#distinguishing-cases Missing, empty, unchanged, changed same-size, blocked-parent, read-only and symlink outputs separate the skip predicate from writes and error fallback. Compiler emitted-file accounting belongs to its owning host test.
+// @evidence contracts/testing.md#execution-ownership This Go unit calls the driver writer with explicit watch mode on temporary native files; no compiler, child host or process environment mutation is required.
+func TestWriteFileWithWatchMode(t *testing.T) {
+  old := time.Date(2001, time.January, 1, 0, 0, 0, 0, time.UTC)
+
+  t.Run("missing and changed", func(t *testing.T) {
+    file := filepath.Join(t.TempDir(), "nested", "out.js")
+    if err := writeFileWithWatchMode(file, "first", true); err != nil {
+      t.Fatal(err)
+    }
+    if err := writeFileWithWatchMode(file, "other", true); err != nil {
+      t.Fatal(err)
+    }
+    data, err := os.ReadFile(file)
+    if err != nil || string(data) != "other" {
+      t.Fatalf("changed output = %q, %v", data, err)
+    }
+    if err := writeFileWithWatchMode(file, "", true); err != nil {
+      t.Fatal(err)
+    }
+    data, err = os.ReadFile(file)
+    if err != nil || len(data) != 0 {
+      t.Fatalf("empty output = %q, %v", data, err)
+    }
+    if err := os.Chtimes(file, old, old); err != nil {
+      t.Fatal(err)
+    }
+    if err := writeFileWithWatchMode(file, "", true); err != nil {
+      t.Fatal(err)
+    }
+    info, err := os.Stat(file)
+    if err != nil || !info.ModTime().Equal(old) {
+      t.Fatalf("empty output was rewritten: %v, %v", info, err)
+    }
+  })
+
+  t.Run("identical watch and ordinary output", func(t *testing.T) {
+    root := t.TempDir()
+    watch := filepath.Join(root, "watch.js")
+    normal := filepath.Join(root, "normal.js")
+    for _, file := range []string{watch, normal} {
+      if err := os.WriteFile(file, []byte("same"), 0o600); err != nil {
+        t.Fatal(err)
+      }
+      if err := os.Chtimes(file, old, old); err != nil {
+        t.Fatal(err)
+      }
+    }
+    before, err := os.Stat(watch)
+    if err != nil {
+      t.Fatal(err)
+    }
+    if err := writeFileWithWatchMode(watch, "same", true); err != nil {
+      t.Fatal(err)
+    }
+    after, err := os.Stat(watch)
+    if err != nil {
+      t.Fatal(err)
+    }
+    if !after.ModTime().Equal(before.ModTime()) || after.Mode() != before.Mode() {
+      t.Fatalf("unchanged watch metadata changed: before=%v after=%v", before, after)
+    }
+    if err := writeFileWithWatchMode(normal, "same", false); err != nil {
+      t.Fatal(err)
+    }
+    normalAfter, err := os.Stat(normal)
+    if err != nil {
+      t.Fatal(err)
+    }
+    if normalAfter.ModTime().Equal(old) {
+      t.Fatal("ordinary identical output was not rewritten")
+    }
+  })
+
+  t.Run("blocked parent", func(t *testing.T) {
+    parent := filepath.Join(t.TempDir(), "parent")
+    if err := os.WriteFile(parent, []byte("file"), 0o600); err != nil {
+      t.Fatal(err)
+    }
+    if err := writeFileWithWatchMode(filepath.Join(parent, "out.js"), "x", true); err == nil {
+      t.Fatal("watch writer accepted a blocked parent")
+    }
+  })
+
+  t.Run("read-only output", func(t *testing.T) {
+    root := t.TempDir()
+    watch := filepath.Join(root, "watch.js")
+    normal := filepath.Join(root, "normal.js")
+    for _, file := range []string{watch, normal} {
+      if err := os.WriteFile(file, []byte("same"), 0o600); err != nil {
+        t.Fatal(err)
+      }
+      if err := os.Chmod(file, 0o400); err != nil {
+        t.Fatal(err)
+      }
+    }
+    watchErr := writeFileWithWatchMode(watch, "same", true)
+    normalErr := writeFileWithWatchMode(normal, "same", false)
+    if (watchErr == nil) != (normalErr == nil) {
+      t.Fatalf("read-only write error differs: watch=%v normal=%v", watchErr, normalErr)
+    }
+  })
+
+  t.Run("symlink output", func(t *testing.T) {
+    root := t.TempDir()
+    target := filepath.Join(root, "target.js")
+    link := filepath.Join(root, "link.js")
+    if err := os.WriteFile(target, []byte("same"), 0o600); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.Symlink(target, link); err != nil {
+      t.Skipf("symlink unavailable: %v", err)
+    }
+    if err := os.Chtimes(target, old, old); err != nil {
+      t.Fatal(err)
+    }
+    if err := writeFileWithWatchMode(link, "same", true); err != nil {
+      t.Fatal(err)
+    }
+    info, err := os.Lstat(link)
+    if err != nil || info.Mode()&os.ModeSymlink == 0 {
+      t.Fatalf("output symlink was replaced: %v, %v", info, err)
+    }
+    targetInfo, err := os.Stat(target)
+    if err != nil || targetInfo.ModTime().Equal(old) {
+      t.Fatalf("symlink target was not rewritten: %v, %v", targetInfo, err)
+    }
+  })
+}

package/internal/packageartifacts/manifest.go

@@ -0,0 +1,288 @@
+// Package packageartifacts validates published Go cache actions before they enter a local base.
+package packageartifacts
+
+import (
+  "bytes"
+  "crypto/sha256"
+  "encoding/hex"
+  "encoding/json"
+  "errors"
+  "fmt"
+  "io"
+  "net"
+  "net/url"
+  "strings"
+)
+
+const MaxManifestBytes = 16 << 20
+
+const MaxPackBytes = 512 << 20
+
+const MaxPackDecodedBytes = 4 << 30
+
+// Manifest is a candidate catalog. Only Go's full ActionID decides a cache hit.
+// Its exact serialized bytes must match a digest carried by the trusted release package.
+//
+// @evidence contracts/common.md#principled-implementation Release provenance, Go selection, transport packs and complete action associations are kept together so admission cannot use an unauthenticated partial catalog.
+// @evidence contracts/common.md#clear-and-simple-design One versioned value is decoded and validated before any pack or action is exposed.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The graph digest diagnoses a build; it never substitutes for Go's action key or a release-pinned digest.
+// @evidence contracts/common.md#meaningful-documentation The comment identifies candidate-only selection and the external trust prerequisite.
+//
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This JSON value has no native path or process operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The type chooses no algorithm; parsing and traversal belong to ParseTrustedManifest.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The value owns no retained computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The value owns no external resource.
+type Manifest struct {
+  Schema       int      `json:"schema"`
+  Release      string   `json:"release"`
+  SourceCommit string   `json:"sourceCommit"`
+  Tuple        Tuple    `json:"tuple"`
+  GraphSHA256  string   `json:"graphSHA256"`
+  Packs        []Pack   `json:"packs"`
+  Actions      []Action `json:"actions"`
+}
+
+// Tuple selects candidate packs, while Go validates actual package actions.
+// Initial publisher coverage is limited to an observed effective CGO_ENABLED=0.
+//
+// @evidence contracts/common.md#principled-implementation The recorded Go tool, target, features and build policy choose a possible pack without claiming that equal tuple fields imply equal ActionIDs.
+// @evidence contracts/common.md#clear-and-simple-design Selection fields form one value and leave actual cache matching to Go.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The CGO field records the observed setting and cannot be rewritten to manufacture coverage.
+// @evidence contracts/common.md#meaningful-documentation The comment states the tuple's limited authority and initial native eligibility.
+//
+// @evidenceExclude contracts/portability.md#os-neutral-implementation These are Go-reported target strings, not native filesystem paths or process calls.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The type chooses no algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The type retains no result across requests.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The type owns no handle or task.
+type Tuple struct {
+  GoVersion     string            `json:"goVersion"`
+  GoToolSHA256  string            `json:"goToolSHA256"`
+  GOOS          string            `json:"goos"`
+  GOARCH        string            `json:"goarch"`
+  Architecture  map[string]string `json:"architecture"`
+  CGOEnabled    string            `json:"cgoEnabled"`
+  GoExperiment  string            `json:"goExperiment"`
+  BuildFlags    []string          `json:"buildFlags"`
+  BuildTags     []string          `json:"buildTags"`
+  ToolIDsSHA256 string            `json:"toolIDsSHA256"`
+}
+
+// Pack describes one immutable compressed transport object and its decoded limit.
+//
+// @evidence contracts/common.md#principled-implementation A transport digest and compressed/decoded counts are separate so admission can bound both transfer and extracted bodies.
+// @evidence contracts/common.md#clear-and-simple-design One pack record carries the bytes and count limits needed by its reader.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A pack hash from the pack itself is not producer authority; the enclosing Manifest requires a separately trusted digest.
+// @evidence contracts/common.md#meaningful-documentation The comment names the immutable object and decoded limit; fields carry their JSON units in names.
+//
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The name is a transport identifier, not an interpreted native path.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The record chooses no computation strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The record retains no cross-request computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record owns no downloaded bytes or handle.
+type Pack struct {
+  Name         string `json:"name"`
+  URL          string `json:"url"`
+  SHA256       string `json:"sha256"`
+  Length       int64  `json:"length"`
+  DecodedBytes int64  `json:"decodedBytes"`
+  FileCount    int    `json:"fileCount"`
+}
+
+// Action associates a complete Go cache key with the exact body Go produced.
+// Evidence is diagnostic; no package path, graph digest or displayed build ID replaces ActionID.
+//
+// @evidence contracts/common.md#principled-implementation The full Go action and output identities own lookup; package/module/source/command/dependency fields explain a captured association without changing it.
+// @evidence contracts/common.md#clear-and-simple-design Archive and opaque bodies share one association because both use the same Go cache protocol.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The package annotation never synthesizes a key, and an opaque record cannot be silently interpreted as an archive.
+// @evidence contracts/common.md#meaningful-documentation The comment distinguishes cache authority from diagnostic evidence.
+//
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Paths are Go package/module identifiers and full digests, not native filesystem paths.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The record selects no algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The record retains no computation across calls.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record owns no body or handle.
+type Action struct {
+  ActionID          string   `json:"actionID"`
+  OutputID          string   `json:"outputID"`
+  BodySHA256        string   `json:"bodySHA256"`
+  BodyLength        int64    `json:"bodyLength"`
+  Pack              string   `json:"pack"`
+  Kind              string   `json:"kind"`
+  PackagePath       string   `json:"packagePath"`
+  ModulePath        string   `json:"modulePath"`
+  ModuleVersion     string   `json:"moduleVersion"`
+  ModuleRole        string   `json:"moduleRole"`
+  SelectedSourceSHA string   `json:"selectedSourceSHA256"`
+  CommandSHA256     string   `json:"commandSHA256"`
+  DirectInputs      []string `json:"directInputs"`
+}
+
+// ParseTrustedManifest checks the raw release-pinned digest before decoding any mapping.
+// The caller must obtain expectedSHA256 from authenticated release metadata, never from raw.
+//
+// @evidence contracts/common.md#principled-implementation SHA-256 of exact bounded bytes is compared with an external trusted digest before strict schema and full 32-byte action/output validation; Go alone computes the keys.
+// @evidence contracts/common.md#clear-and-simple-design One decoder owns producer authentication, schema and association checks before returning a usable manifest.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A digest supplied by the same untrusted manifest is never accepted as authority; duplicate conflicting actions fail rather than choosing a convenient output.
+// @evidence contracts/common.md#meaningful-documentation The comment states the trust source and that the raw bytes, not a reserialized form, are authenticated.
+//
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This byte decoder does no native path or process operation.
+// @evidence contracts/performance.md#efficient-algorithms It hashes at most 16 MiB of input once, then decodes and traverses at most 64 packs and 100000 actions; maps give expected constant-time identity lookup with memory proportional to those populations.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Release bytes are checked for each call; this function retains no result or in-flight work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only bounded call-local bytes and maps are retained; the caller owns raw input and returned manifest lifetime.
+func ParseTrustedManifest(raw []byte, expectedSHA256 string) (Manifest, error) {
+  var manifest Manifest
+  if len(raw) == 0 || len(raw) > MaxManifestBytes {
+    return manifest, fmt.Errorf("artifact manifest length %d is outside (0,%d]", len(raw), MaxManifestBytes)
+  }
+  if !validSHA256(expectedSHA256) {
+    return manifest, errors.New("artifact manifest has no valid trusted digest")
+  }
+  digest := sha256.Sum256(raw)
+  if hex.EncodeToString(digest[:]) != expectedSHA256 {
+    return manifest, errors.New("artifact manifest differs from trusted release digest")
+  }
+  decoder := json.NewDecoder(bytes.NewReader(raw))
+  decoder.DisallowUnknownFields()
+  if err := decoder.Decode(&manifest); err != nil {
+    return Manifest{}, fmt.Errorf("decode artifact manifest: %w", err)
+  }
+  var trailing any
+  if err := decoder.Decode(&trailing); err != io.EOF {
+    return Manifest{}, errors.New("artifact manifest contains trailing data")
+  }
+  if err := manifest.validate(); err != nil {
+    return Manifest{}, err
+  }
+  return manifest, nil
+}
+
+func (manifest Manifest) validate() error {
+  if manifest.Schema != 1 {
+    return fmt.Errorf("unsupported artifact manifest schema %d", manifest.Schema)
+  }
+  if manifest.Release == "" || !validCommit(manifest.SourceCommit) || !validSHA256(manifest.GraphSHA256) {
+    return errors.New("artifact manifest has incomplete release provenance")
+  }
+  tuple := manifest.Tuple
+  if tuple.GoVersion == "" || tuple.GOOS == "" || tuple.GOARCH == "" || tuple.CGOEnabled != "0" || !validSHA256(tuple.GoToolSHA256) || !validSHA256(tuple.ToolIDsSHA256) || len(tuple.BuildFlags) == 0 {
+    return errors.New("artifact manifest has an unsupported or incomplete Go tuple")
+  }
+  if len(manifest.Packs) == 0 || len(manifest.Packs) > 64 || len(manifest.Actions) == 0 || len(manifest.Actions) > 100000 {
+    return errors.New("artifact manifest exceeds pack or action count policy")
+  }
+  packs := make(map[string]Pack, len(manifest.Packs))
+  for _, pack := range manifest.Packs {
+    if !validName(pack.Name) || !validPackURL(pack.URL) || !validSHA256(pack.SHA256) || pack.Length <= 0 || pack.Length > MaxPackBytes || pack.DecodedBytes < 0 || pack.DecodedBytes > MaxPackDecodedBytes || pack.FileCount <= 0 {
+      return fmt.Errorf("invalid artifact pack %q", pack.Name)
+    }
+    if _, exists := packs[pack.Name]; exists {
+      return fmt.Errorf("duplicate artifact pack %q", pack.Name)
+    }
+    packs[pack.Name] = pack
+  }
+  actions := make(map[string]Action, len(manifest.Actions))
+  outputs := make(map[string]int64, len(manifest.Actions))
+  outputPacks := make(map[string]string, len(manifest.Actions))
+  packOutputs := make(map[string]map[string]int64, len(manifest.Packs))
+  for _, action := range manifest.Actions {
+    if !validSHA256(action.ActionID) || !validSHA256(action.OutputID) || action.BodySHA256 != action.OutputID || action.BodyLength < 0 {
+      return fmt.Errorf("invalid full action/output identity %q", action.ActionID)
+    }
+    if action.BodyLength == 0 && action.OutputID != emptyBodySHA256 {
+      return fmt.Errorf("invalid empty body identity for action %s", action.ActionID)
+    }
+    if action.Kind != "archive" && action.Kind != "opaque" {
+      return fmt.Errorf("unsupported cache body kind %q", action.Kind)
+    }
+    if action.Kind == "archive" && (action.PackagePath == "" || action.ModuleRole == "" || !validSHA256(action.SelectedSourceSHA) || !validSHA256(action.CommandSHA256)) {
+      return fmt.Errorf("incomplete package evidence for action %s", action.ActionID)
+    }
+    if _, exists := packs[action.Pack]; !exists {
+      return fmt.Errorf("action %s names unknown pack %q", action.ActionID, action.Pack)
+    }
+    if previous, exists := actions[action.ActionID]; exists {
+      if previous.OutputID != action.OutputID || previous.BodyLength != action.BodyLength {
+        return fmt.Errorf("conflicting publisher mapping for action %s", action.ActionID)
+      }
+      return fmt.Errorf("duplicate publisher action %s", action.ActionID)
+    }
+    if length, exists := outputs[action.OutputID]; exists && length != action.BodyLength {
+      return fmt.Errorf("conflicting body length for output %s", action.OutputID)
+    }
+    if owner, exists := outputPacks[action.OutputID]; exists && owner != action.Pack {
+      return fmt.Errorf("output %s is duplicated across packs", action.OutputID)
+    }
+    for _, input := range action.DirectInputs {
+      if !validSHA256(input) {
+        return fmt.Errorf("action %s has a malformed direct input", action.ActionID)
+      }
+    }
+    actions[action.ActionID] = action
+    outputs[action.OutputID] = action.BodyLength
+    outputPacks[action.OutputID] = action.Pack
+    if packOutputs[action.Pack] == nil {
+      packOutputs[action.Pack] = make(map[string]int64)
+    }
+    packOutputs[action.Pack][action.OutputID] = action.BodyLength
+  }
+  for _, pack := range manifest.Packs {
+    var total int64
+    for _, length := range packOutputs[pack.Name] {
+      if length > pack.DecodedBytes-total {
+        return fmt.Errorf("pack %q exceeds its decoded byte count", pack.Name)
+      }
+      total += length
+    }
+    if len(packOutputs[pack.Name]) != pack.FileCount || total != pack.DecodedBytes {
+      return fmt.Errorf("pack %q has inconsistent decoded counts", pack.Name)
+    }
+  }
+  return nil
+}
+
+const emptyBodySHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+
+func validSHA256(value string) bool {
+  if len(value) != 64 {
+    return false
+  }
+  for _, char := range value {
+    if !strings.ContainsRune("0123456789abcdef", char) {
+      return false
+    }
+  }
+  return true
+}
+
+func validCommit(value string) bool {
+  if len(value) != 40 && len(value) != 64 {
+    return false
+  }
+  for _, char := range value {
+    if !strings.ContainsRune("0123456789abcdef", char) {
+      return false
+    }
+  }
+  return true
+}
+
+func validName(value string) bool {
+  if value == "" || len(value) > 80 {
+    return false
+  }
+  for _, char := range value {
+    if !strings.ContainsRune("abcdefghijklmnopqrstuvwxyz0123456789-", char) {
+      return false
+    }
+  }
+  return true
+}
+
+func validPackURL(value string) bool {
+  parsed, err := url.Parse(value)
+  if err != nil || parsed.User != nil || parsed.Host == "" || parsed.Fragment != "" {
+    return false
+  }
+  if parsed.Scheme == "https" {
+    return true
+  }
+  return parsed.Scheme == "http" && net.ParseIP(parsed.Hostname()) != nil && net.ParseIP(parsed.Hostname()).IsLoopback()
+}