ttsc 0.30.3 → 0.31.0

package/src/structures/internal/TtscBuildResult.ts

@@ -1,15 +1,85 @@
 import type { ITtscCompilerDiagnostic } from "../ITtscCompilerDiagnostic";
+import type { ITtscCompilerTransformation } from "../ITtscCompilerTransformation";
 
-/** Internal result captured from TypeScript-Go or native plugin sidecars. */
+/**
+ * Internal result captured from TypeScript-Go or native plugin sidecars.
+ *
+ * @evidence contracts/common.md#principled-implementation Exit status, actual normal completion, diagnostics, streams, check-generation witnesses and optional emitted-source provenance remain separate. Absent provenance, an unknown output's empty source list and a complete empty output map differ; null input witnesses record absence while missing keys establish no reusable proof.
+ * @evidence contracts/common.md#clear-and-simple-design One result record carries process facts and separately requested emitted-file/provenance data without making display-text parsing responsible for source ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Streams derive from actual host output, though failure normalization can move stdout into stderr and phase composition can concatenate them. Numeric status remains separate from normal-completion proof; neither diagnostic text nor normalization invents successful execution or source ownership.
+ * @evidence contracts/common.md#meaningful-documentation Native comments state status versus actual completion, emitted-list availability, generation ownership, null versus missing witnesses and unknown/ambiguous provenance states; member and tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Provenance distinguishes actual absolute native output spelling from physical source identity captured by the producer or stable external observations; neither path is case-folded or reconstructed from a URL, and each producer owns its resolution premise.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
 export interface TtscBuildResult {
-  /** Structured diagnostics collected from compiler output. */
+  /** Compiler-time graph of the same check generation, when transported. */
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
+  /** Structured compiler/plugin diagnostics, supplied or parsed from output. */
   diagnostics: ITtscCompilerDiagnostic[];
+
   /** Files written by the build when emitted-file listing was requested. */
   emittedFiles?: string[];
+
+  /**
+   * Emitter provenance for actual written JavaScript outputs. Keys are absolute
+   * native output spellings; values retain contributing physical source paths.
+   * Native producers capture those identities in the compile generation. The
+   * external compiler adapter instead requires matching pre/post source
+   * selection, effective options, physical identities and contents, including
+   * the selected executable. It cannot detect a concurrent change restored
+   * between observations.
+   *
+   * Multiple sources are ambiguous for single-file routing, and an empty list
+   * means the producer could not establish full ownership under its premise.
+   *
+   * Absent means unavailable or an older producer. A present empty map means a
+   * supported producer reported no eligible written JavaScript output.
+   * Consumers must not infer source ownership from emitted filenames in either
+   * unknown state. Provenance does not by itself establish overall build
+   * success.
+   */
+  emittedSources?: Record<string, readonly string[]>;
+
+  /**
+   * Actual proof-refusal reasons for reported output paths. Diagnostic context
+   * alone establishes no source ownership and does not replace compiler
+   * errors.
+   */
+  emittedSourceProofFailures?: Readonly<Record<string, string>>;
+
+  /** Native inputs declared or observed by the contributing check generations. */
+  hostInputs?: string[];
+
+  /**
+   * Generation-captured SHA-256 witnesses, keyed by declared native input. Null
+   * records observed absence; a missing key supplies no reusable proof.
+   */
+  hostInputHashes?: Record<string, string | null>;
+
+  /**
+   * Generation-captured physical paths, or null for observed absence. Missing
+   * keys preserve unavailable or conflicting proof without a later realpath.
+   */
+  hostInputRealpaths?: Record<string, string | null>;
+
+  /** A contributing producer explicitly reported incomplete observations. */
+  observationsComplete?: false;
+
+  /**
+   * Actual spawn completion fact before null-status coercion. True requires a
+   * present native exit status and no terminating signal; absence proves no
+   * completion premise for generation-owned metadata.
+   */
+  processCompletedNormally?: boolean;
+
   /** Process-style exit status. `0` means success. */
   status: number;
-  /** Captured stdout from TypeScript-Go or native plugin sidecars. */
+
+  /** Host stdout text after any failure normalization or phase composition. */
   stdout: string;
-  /** Captured stderr from TypeScript-Go or native plugin sidecars. */
+
+  /** Host stderr text after any failure normalization or phase composition. */
   stderr: string;
 }

package/src/structures/internal/TtscCommonOptions.ts

@@ -3,19 +3,34 @@ import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
 /**
  * Internal options shared by the CLI build, single-file emit, and runtime
  * paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional overrides preserve default resolution and distinguish disabled plugins from an explicit replacement list; passthrough tokens retain the native compiler's own option parser authority.
+ * @evidence contracts/common.md#clear-and-simple-design The shared record contains cross-path project/process policy once; build and single-file options extend it with their own operation-specific controls.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native binary/env injection is a supported embedding boundary; compiler options remain tokens rather than hardcoded approximations of the entire native schema.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain option ownership, config discovery origins, threading and plugin override states; paragraphs, member and tag spacing follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path inputs and Node environment data stay separate from passthrough argv tokens, enabling OS-neutral spawn/path handling without shell quoting assumptions or platform-specific executable names in this representation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
  */
 export interface TtscCommonOptions {
   /**
    * Explicit TypeScript-Go executable.
    *
-   * When supplied, ttsc skips package-based tsgo resolution and shells out to
-   * this binary directly.
+   * A nonempty override must be an existing absolute path. It bypasses
+   * package-based resolution; the native spawn owns execution failures.
    */
   binary?: string;
+
   /** Working directory for config discovery and relative file paths. */
   cwd?: string;
-  /** Project root override for generated tsconfig wrappers. */
+
+  /**
+   * Selected project root, resolved from `cwd` independently of config
+   * location.
+   */
   projectRoot?: string;
+
   /**
    * Directory that anchors plugin config-file discovery and relative
    * `configFile` resolution (forwarded to plugin processes as
@@ -24,37 +39,67 @@ export interface TtscCommonOptions {
    * tsconfig's own directory.
    */
   pluginConfigDir?: string;
+
   /** Environment variables merged over `process.env` for child processes. */
   env?: NodeJS.ProcessEnv;
+
   /** Explicit root directory for compiled source-plugin cache artifacts. */
   cacheDir?: string;
-  /** Normalize compiler output so diagnostics can be parsed structurally. */
+
+  /** Request nonpretty compiler output unless passthrough controls `--pretty`. */
   structuredDiagnostics?: boolean;
+
   /**
    * Run TypeScript-Go single-threaded — one checker, serial parse/check/emit.
    * Mirrors `tsgo --singleThreaded`. Useful for deterministic debugging and CI
    * repro.
    */
   singleThreaded?: boolean;
+
   /**
-   * Type-checker pool size, mirroring `tsgo --checkers`. `undefined` leaves
-   * TypeScript-Go's default; ignored when `singleThreaded` is set.
+   * Requested checker pool size, mirroring `tsgo --checkers`; `singleThreaded`
+   * takes precedence. Check hosts receive this only when they declare support.
+   * The source-plugin driver clamps its serial transform Program to one
+   * checker; direct TypeScript-Go execution otherwise owns its default and pool
+   * policy.
    */
   checkers?: number;
+
   /**
-   * CLI tokens ttsc did not recognize as its own, forwarded verbatim to the
-   * underlying `tsgo` invocation. This is how a tsgo flag ttsc has no first-
-   * class option for (`--strict`, `--target es2020`, `--listFiles`, …) still
-   * reaches the compiler: ttsc owns its own flags and lets tsgo — which has the
-   * complete, arity-aware option parser — handle the rest.
+   * Compiler-option tokens retaining their boundaries and order. Direct tsgo
+   * execution forwards them; native hosts receive a JSON compiler-option
+   * payload with timing flags omitted because host timing has its own channel.
+   * tsgo owns option parsing, including flags without a first-class ttsc option
+   * such as `--strict`, `--target es2020` and `--listFiles`. Internal output
+   * isolation can append destination overrides after these tokens.
    */
   passthrough?: readonly string[];
+
+  /**
+   * Validated visible CLI project assignments at their original positions in
+   * passthrough. Only the launcher supplies this metadata; explicit compiler
+   * instances retain their resolvedProject authority instead.
+   */
+  compilerProjectSelections?: readonly {
+    passthroughIndex: number;
+    value: string;
+  }[];
+
+  /**
+   * Retained native compiler argument base when project selection redirects
+   * the Program to a different root. Absent retains the selected project root.
+   * Response frames and relative native options use this base; plugin/rule
+   * context and config-relative paths retain their separate project authority.
+   */
+  compilerArgsCwd?: string;
+
   /**
    * Override project plugin loading for this invocation.
    *
-   * - `false`: ignore `compilerOptions.plugins` completely.
-   * - Array: use these plugin entries instead of the project config entries.
-   * - `undefined`: use the project config entries as written.
+   * - `false`: disable project plugin loading and dependency discovery.
+   * - Array: use these entries instead of config and dependency discovery.
+   * - `undefined`: use the project config entries and discover plugins from
+   *   direct dependencies.
    */
   plugins?: readonly ITtscProjectPluginConfig[] | false;
 }

package/src/structures/internal/TtscSingleFileEmitOptions.ts

@@ -1,18 +1,68 @@
 import type { ITtscProjectInputSnapshot } from "./ITtscProjectInputSnapshot";
 import type { TtscCommonOptions } from "./TtscCommonOptions";
 
-/** Internal options for emitting one source file through the file-argument path. */
+/**
+ * Internal options for emitting one source file through the file-argument path.
+ *
+ * @evidence contracts/common.md#principled-implementation The required source file selects a single-file operation; optional config/output controls preserve discovery and destination defaults, while callbacks publish distinct source and project-rule watch inputs.
+ * @evidence contracts/common.md#clear-and-simple-design Shared process policy is inherited, and two explicit notifications keep plugin-source roots separate from richer project-rule topology.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Watch notifications are caller hooks receiving actual discovered inputs, not foreign watcher replacements or synthetic paths for tests.
+ * @evidence contracts/common.md#meaningful-documentation Native comments identify path bases, config discovery, quiet behavior and callback payloads; member and tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native file/config/output paths retain their documented resolution bases, and watch inputs are structured path populations; no command string or POSIX-only parsing is encoded in the input shape.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
 export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
   /** Source file to emit. Absolute paths and `cwd`-relative paths work. */
   file: string;
-  /** Project config owning `file`; discovered from `file` when omitted. */
+
+  /** Project config resolved from `cwd`; discovered from `file` when omitted. */
   tsconfig?: string;
-  /** Optional output file path. */
+
+  /** Optional output file, absolute or resolved from the invocation `cwd`. */
   out?: string;
+
   /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
   quiet?: boolean;
+
   /** Receive native-plugin source roots when a watch owns this invocation. */
-  onWatchInputs?: (inputs: readonly string[]) => void;
+  onWatchInputs?: TtscPluginSourceInputsHandler;
+
   /** Receive project-rule filesystem inputs when a watch owns this invocation. */
-  onProjectInputs?: (inputs: ITtscProjectInputSnapshot) => void;
+  onProjectInputs?: TtscProjectInputsHandler;
 }
+
+/**
+ * Receive selected plugin build-source roots for the invocation's watch owner.
+ *
+ * Executable modules, linked source roots, contributors and external local
+ * module replacements can be reported. ttsc's own package sources are omitted;
+ * this notification is not the complete compiler or project-rule input graph.
+ *
+ * @evidence contracts/common.md#principled-implementation Readonly roots describe the actual native-plugin sources whose later edits need observation.
+ * @evidence contracts/common.md#clear-and-simple-design A void notification leaves watcher construction and lifetime with the invocation owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported callback neither replaces foreign watchers nor fabricates fixture-specific roots.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the source population and owner before acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source paths pass through without separator rewriting, alias collapse or an encoded OS-specific watcher.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type TtscPluginSourceInputsHandler = (inputs: readonly string[]) => void;
+
+/**
+ * Receive the discovered project-rule filesystem topology for the watch owner.
+ *
+ * @evidence contracts/common.md#principled-implementation The snapshot retains exact, glob and reload dependencies rather than reducing them to plugin-source roots.
+ * @evidence contracts/common.md#clear-and-simple-design A separate void notification transfers topology without assigning watcher lifetime to the emit options.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A discovered rule snapshot crosses a supported boundary without replacing watcher internals or inventing passing inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the project-rule payload and watch owner before the separated tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The snapshot retains native paths, explicit glob grammar and declared versus physical identities without blanket case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type TtscProjectInputsHandler = (
+  inputs: ITtscProjectInputSnapshot,
+) => void;

package/tools/gen_shims/main.go

@@ -6,16 +6,16 @@
 // Copyright (c) 2025 VoidZero Inc. & Contributors.
 // Copyright (c) 2025 typescript-eslint and other contributors.
 // Copyright (c) 2026 Jeongho Nam (ttsc adaptation — host-specific packages
-// list and extra_shim lookup path; generator algorithm unchanged).
+// list, extra_shim lookup path and selected private field support).
 //
 // Usage:
 //
 //  cd packages/ttsc
-//  go run ./tools/gen_shims
+//  go run -modfile=tools/gen_shims/go.mod ./tools/gen_shims/main.go
 //
-// Each shim directory (`packages/ttsc/shim/<name>`) must contain an
-// `extra-shim.json` file; the generator writes its output to
-// `packages/ttsc/shim/<name>/shim.go`.
+// Each shim directory (`packages/ttsc/shim/<name>`) may contain an
+// `extra-shim.json` file (an absent file means no extras); the generator writes its output to
+// `packages/ttsc/shim/<name>/shim.go` or a configured private support file.
 package main
 
 import (
@@ -49,6 +49,7 @@ var packagesToShim = []string{
   "core",
   "parser",
   "scanner",
+  "stringutil",
   "tsoptions",
   "tspath",
   "vfs",
@@ -69,6 +70,9 @@ type ExtraShim struct {
   // ExtraFields maps type name → field names whose values should be exposed
   // through unsafe pointer casts (used when go:linkname cannot reach them).
   ExtraFields map[string][]string
+  // ExtraFieldFiles routes selected field accessors to private generated
+  // support beside a hand-maintained shim. Other fields remain in shim.go.
+  ExtraFieldFiles map[string]string
   // IgnoreFunctions lists exported function names that gen_shims should skip
   // entirely, typically because the caller supplies a hand-written alternative.
   IgnoreFunctions []string
@@ -108,18 +112,15 @@ func main() {
   if err != nil {
     log.Fatalf("gen_shims: packages.Load: %v", err)
   }
+  if err := validateShimPackages(loaded, fullNames); err != nil {
+    log.Fatalf("gen_shims: packages.Load: %v", err)
+  }
 
   var shimHeaderBuilder strings.Builder
   var shimBuilder strings.Builder
   var tempBuffer bytes.Buffer
 
   for _, pkg := range loaded {
-    if len(pkg.Errors) != 0 {
-      for _, e := range pkg.Errors {
-        fmt.Fprintln(os.Stderr, "gen_shims:", e)
-      }
-      log.Fatalf("gen_shims: package %s failed to load (see errors above)", pkg.PkgPath)
-    }
     shimDirPath := path.Join("./shim/", strings.TrimPrefix(pkg.PkgPath, tsgoInternalPrefix))
 
     var extraShim ExtraShim
@@ -322,6 +323,21 @@ func main() {
         }
 
         if _, ok := matchedExtraFields[name]; isNamed && ok {
+          if filename, separate := extraShim.ExtraFieldFiles[name]; separate {
+            output, err := generatePrivateFieldSupport(named, extraShim.ExtraFields[name], pkg.Name)
+            if err != nil {
+              log.Fatalf("gen_shims: field support %s: %v", name, err)
+            }
+            if path.Base(filename) != filename || !strings.HasSuffix(filename, "_gen.go") {
+              log.Fatalf("gen_shims: invalid generated field support filename %q", filename)
+            }
+            if err := os.WriteFile(path.Join(shimDirPath, filename), output, 0o644); err != nil {
+              log.Fatal(err)
+            }
+            fmt.Fprintf(os.Stdout, "gen_shims: wrote %s (private field support)\n", path.Join(shimDirPath, filename))
+            matchedExtraFields[name] = true
+            continue
+          }
           importPackage("unsafe", true)
           matchedExtraFields[name] = true
           mirrorStructName := "extra_" + name
@@ -484,6 +500,103 @@ func main() {
   }
 }
 
+// validateShimPackages admits a complete, error-free package population before
+// generation opens any output file. packages.Load can report module-resolution
+// failures through an empty result with no top-level error.
+//
+// @evidence contracts/common.md#principled-implementation Every requested identity must occur exactly once and every returned package must be requested and error-free, preventing incomplete upstream observations from authorizing generated writes.
+// @evidence contracts/common.md#clear-and-simple-design One admission pass precedes all per-package writes and reports the complete returned population's problems together.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The boundary validates loader observations without suppressing Go module failures or inventing package contents.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the empty-success loader behavior and the before-write admission guarantee.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Package import identities are Go identifiers; this validator performs no native filesystem or process operation.
+// @evidence contracts/performance.md#efficient-algorithms Requested and returned identities are counted with maps; work follows their population and diagnostic text, with no package reload.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This validates one actual load result and caches no mutable compiler-source observation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Count maps and diagnostics are call-local; the caller retains loaded package ownership and receives only an error.
+func validateShimPackages(loaded []*packages.Package, requested []string) error {
+  if len(requested) == 0 {
+    return fmt.Errorf("no shim packages requested")
+  }
+  counts := make(map[string]int, len(requested))
+  for _, name := range requested {
+    counts[name] = 0
+  }
+  var problems []string
+  for _, pkg := range loaded {
+    if pkg == nil {
+      problems = append(problems, "nil package result")
+      continue
+    }
+    count, expected := counts[pkg.PkgPath]
+    if !expected {
+      problems = append(problems, "unexpected package "+pkg.PkgPath)
+    } else {
+      counts[pkg.PkgPath] = count + 1
+    }
+    for _, failure := range pkg.Errors {
+      problems = append(problems, failure.Error())
+    }
+  }
+  for _, name := range requested {
+    switch count := counts[name]; {
+    case count == 0:
+      problems = append(problems, "missing package "+name)
+    case count != 1:
+      problems = append(problems, fmt.Sprintf("package %s loaded %d times", name, count))
+    }
+  }
+  if len(problems) != 0 {
+    return fmt.Errorf("incomplete shim package load:\n%s", strings.Join(problems, "\n"))
+  }
+  return nil
+}
+
+// generatePrivateFieldSupport derives a private accessor and its complete
+// struct layout from the loaded upstream type. It does not expose raw state as
+// a public producer; the hand-maintained operation owns its usable lifetime.
+func generatePrivateFieldSupport(named *types.Named, fields []string, packageName string) ([]byte, error) {
+  structure, ok := named.Underlying().(*types.Struct)
+  if !ok {
+    return nil, fmt.Errorf("%s is not a struct", named.Obj().Name())
+  }
+  imports := map[string]string{"unsafe": "unsafe"}
+  qualifier := func(pkg *types.Package) string {
+    imports[pkg.Path()] = pkg.Name()
+    return pkg.Name()
+  }
+  var body strings.Builder
+  mirror := "extra_" + named.Obj().Name()
+  fmt.Fprintf(&body, "type %s struct {\n", mirror)
+  available := map[string]*types.Var{}
+  for field := range structure.Fields() {
+    available[field.Name()] = field
+    // Every field participates in layout, including fields not being read.
+    if !field.Embedded() {
+      fmt.Fprintf(&body, "  %s ", field.Name())
+    }
+    body.WriteString(types.TypeString(field.Type(), qualifier))
+    body.WriteByte('\n')
+  }
+  body.WriteString("}\n\n")
+  for _, name := range fields {
+    field, exists := available[name]
+    if !exists {
+      return nil, fmt.Errorf("%s has no field %s", named.Obj().Name(), name)
+    }
+    getter := strings.ToLower(named.Obj().Name()[:1]) + named.Obj().Name()[1:] + "_" + name
+    fmt.Fprintf(&body, "func %s(value *%s) %s {\n  return ((*%s)(unsafe.Pointer(value))).%s\n}\n", getter,
+      types.TypeString(named, qualifier), types.TypeString(field.Type(), qualifier), mirror, name)
+  }
+  var output strings.Builder
+  output.WriteString("// Code generated by packages/ttsc/tools/gen_shims. DO NOT EDIT.\n\n")
+  fmt.Fprintf(&output, "package %s\n\nimport (\n", packageName)
+  for _, location := range slices.Sorted(maps.Keys(imports)) {
+    fmt.Fprintf(&output, "  %s %q\n", imports[location], location)
+  }
+  output.WriteString(")\n\n")
+  output.WriteString(body.String())
+  return []byte(output.String()), nil
+}
+
 // isHandMaintained reports whether the given shim file opts out of regeneration
 // by carrying the magic marker `// gen_shims:hand-maintained` within its first
 // 200 bytes. Hand-maintained shim files combine generated re-exports with

package/tools/gen_shims/package_load_admission_rejects_incomplete_results_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+  "strings"
+  "testing"
+
+  "golang.org/x/tools/go/packages"
+)
+
+// TestPackageLoadAdmissionRejectsIncompleteResults verifies incomplete loader
+// observations cannot authorize the generator's output phase.
+//
+// The real pre-write validator receives authored loader result records, so the
+// cases distinguish admission policy without substituting for package loading.
+//
+//  1. Construct complete, missing, duplicate and errored package populations.
+//  2. Invoke the same admission operation that guards generation.
+//  3. Assert success or every independently expected diagnostic fragment.
+//
+// @evidence contracts/testing.md#behavioral-verification Calls the production-used validator and checks success or complete diagnostic messages for accepted and rejected populations, including an error on a later package before generation may write earlier outputs.
+// @evidence contracts/testing.md#independent-expectations Literal requested import identities and loader error records define the population contract independently of generator output.
+// @evidence contracts/testing.md#distinguishing-cases Covers complete reversed-order results, empty and partial loads, unexpected and duplicate identities, nil entries and a later package error; each invalid observation must reject the whole population.
+// @evidence contracts/testing.md#execution-ownership This tools/gen_shims source unit invokes the admission operation in one Go process with authored policy inputs; it loads no foreign package, writes no output and starts no native producer.
+func TestPackageLoadAdmissionRejectsIncompleteResults(t *testing.T) {
+  if err := validateShimPackages(nil, nil); err == nil {
+    t.Fatal("empty generation population was admitted")
+  }
+  first, second := "example.com/internal/first", "example.com/internal/second"
+  requested := []string{first, second}
+  for _, test := range []struct {
+    name     string
+    loaded   []*packages.Package
+    messages []string
+  }{
+    {"complete", []*packages.Package{{PkgPath: second}, {PkgPath: first}}, nil},
+    {"empty", nil, []string{"missing package " + first, "missing package " + second}},
+    {"partial", []*packages.Package{{PkgPath: first}}, []string{"missing package " + second}},
+    {"unexpected", []*packages.Package{{PkgPath: first}, {PkgPath: "other"}}, []string{"unexpected package other", "missing package " + second}},
+    {"duplicate", []*packages.Package{{PkgPath: first}, {PkgPath: first}, {PkgPath: second}}, []string{"loaded 2 times"}},
+    {"nil", []*packages.Package{nil, {PkgPath: second}}, []string{"nil package result", "missing package " + first}},
+    {"late error", []*packages.Package{{PkgPath: first}, {PkgPath: second, Errors: []packages.Error{{Msg: "authored module failure"}}}}, []string{"authored module failure"}},
+  } {
+    t.Run(test.name, func(t *testing.T) {
+      err := validateShimPackages(test.loaded, requested)
+      if test.messages == nil {
+        if err != nil {
+          t.Fatal(err)
+        }
+        return
+      }
+      if err == nil {
+        t.Fatal("incomplete load was admitted")
+      }
+      for _, message := range test.messages {
+        if !strings.Contains(err.Error(), message) {
+          t.Errorf("missing %q in %v", message, err)
+        }
+      }
+    })
+  }
+}

package/tools/gen_shims/private_field_support_preserves_upstream_layout_test.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+  "go/ast"
+  "go/importer"
+  "go/parser"
+  "go/token"
+  "go/types"
+  "runtime"
+  "slices"
+  "strings"
+  "testing"
+)
+
+// Verifies private field support preserves the complete upstream struct layout.
+//
+// Reading one private field still requires every preceding and following field
+// to retain its actual Go type and alignment. The generated accessor must stay
+// private rather than becoming an uninitialized compiler-state producer.
+//
+//  1. Type-check a literal struct with slice, interface and pointer fields.
+//  2. Generate and type-check the real support against those exact types.
+//  3. Compare field order, types, size and offsets, and reject an absent field.
+//
+// @evidence contracts/testing.md#behavioral-verification Real support generation and Go type checking verify the mirror layout and accessor signature; complete layout and private getter assertions detect changed field offsets or an unintended public producer, without executing an unsafe getter read.
+// @evidence contracts/testing.md#independent-expectations The authored upstream fixture fixes four ordered fields and the selected impl pointer. Go's architecture-specific size authority independently establishes alignment and offsets.
+// @evidence contracts/testing.md#distinguishing-cases Slice, interface and pointer fields surround the accessed field; an unknown field must fail, and only the selected private accessor may exist.
+// @evidence contracts/testing.md#execution-ownership This generator source unit runs in tools/gen_shims in one Go process using parser and type-checker operations without a native artifact, installation or subprocess.
+func TestPrivateFieldSupportPreservesUpstreamLayout(t *testing.T) {
+  fset := token.NewFileSet()
+  upstreamFile, err := parser.ParseFile(fset, "upstream.go", `package checker
+type Context struct{}
+type Implementation struct{}
+type Host interface{ CurrentDirectory() string }
+type Verbosity struct{ Level int }
+type NodeBuilder struct {
+  contexts []*Context
+  host Host
+  impl *Implementation
+  verbosity *Verbosity
+}
+`, 0)
+  if err != nil {
+    t.Fatal(err)
+  }
+  upstream, err := (&types.Config{}).Check(tsgoInternalPrefix+"checker", fset, []*ast.File{upstreamFile}, nil)
+  if err != nil {
+    t.Fatal(err)
+  }
+  named := upstream.Scope().Lookup("NodeBuilder").Type().(*types.Named)
+  output, err := generatePrivateFieldSupport(named, []string{"impl"}, "checker")
+  if err != nil {
+    t.Fatal(err)
+  }
+  generated, err := parser.ParseFile(fset, "generated.go", output, 0)
+  if err != nil {
+    t.Fatal(err)
+  }
+  checked, err := (&types.Config{Importer: fieldSupportImporter{upstream}}).Check("fixture/shim/checker", fset, []*ast.File{generated}, nil)
+  if err != nil {
+    t.Fatal(err)
+  }
+  mirror := checked.Scope().Lookup("extra_NodeBuilder").Type().Underlying().(*types.Struct)
+  original := named.Underlying().(*types.Struct)
+  expected := []string{"contexts", "host", "impl", "verbosity"}
+  originalFields := make([]*types.Var, 4)
+  mirrorFields := make([]*types.Var, 4)
+  if mirror.NumFields() != len(expected) {
+    t.Fatalf("mirror fields = %d", mirror.NumFields())
+  }
+  for index, name := range expected {
+    if mirror.Field(index).Name() != name || !types.Identical(mirror.Field(index).Type(), original.Field(index).Type()) {
+      t.Fatalf("field %d lost the authored %s identity", index, name)
+    }
+    originalFields[index], mirrorFields[index] = original.Field(index), mirror.Field(index)
+  }
+  sizes := types.SizesFor("gc", runtime.GOARCH)
+  if sizes.Sizeof(original) != sizes.Sizeof(mirror) || !slices.Equal(sizes.Offsetsof(originalFields), sizes.Offsetsof(mirrorFields)) {
+    t.Fatal("generated mirror changes native field alignment")
+  }
+  getter := checked.Scope().Lookup("nodeBuilder_impl")
+  if getter == nil || getter.Exported() || checked.Scope().Lookup("NodeBuilder_impl") != nil {
+    t.Fatal("field support must expose only a private accessor")
+  }
+  signature := getter.Type().(*types.Signature)
+  if !types.Identical(signature.Results().At(0).Type(), original.Field(2).Type()) {
+    t.Fatal("getter result lost impl type")
+  }
+  if strings.Count(string(output), "func ") != 1 {
+    t.Fatal("unrequested field accessor generated")
+  }
+  if _, err := generatePrivateFieldSupport(named, []string{"missing"}, "checker"); err == nil {
+    t.Fatal("absent field was accepted")
+  }
+}
+
+type fieldSupportImporter struct{ upstream *types.Package }
+
+func (i fieldSupportImporter) Import(path string) (*types.Package, error) {
+  if path == i.upstream.Path() {
+    return i.upstream, nil
+  }
+  return importer.Default().Import(path)
+}