ttsc 0.23.0 → 0.25.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jeongho Nam
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Jeongho Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,8 +8,9 @@ A `typescript-go` toolchain for compiler-powered plugins and type-safe execution
 
 - **`ttsc`**: build, check, and transform.
 - **`ttsx`**: execute TypeScript with type checking.
-- [**`@ttsc/graph`**](https://github.com/samchon/ttsc/tree/master/packages/graph): MCP code graph that reduces agent token usage.
 - [**`@ttsc/lint`**](https://github.com/samchon/ttsc/tree/master/packages/lint): lint violations as compiler errors.
+- [**`@ttsc/evidence`**](https://github.com/samchon/ttsc/tree/master/packages/evidence): 100% requirement coverage, or the build fails.
+- [**`@ttsc/graph`**](https://github.com/samchon/ttsc/tree/master/packages/graph): compiler knowledge graph that cuts agent tokens by 92%.
 - **plugin support**: compiler-powered libraries, such as `typia`.
 
 ## Setup
@@ -35,94 +36,95 @@ That covers the CLI. The integrations each have a short guide:
 - [`@ttsc/metro`](https://ttsc.dev/docs/setup/metro): React Native and Expo.
 - [`@ttsc/vscode`](https://ttsc.dev/docs/setup/vscode): live editor diagnostics.
 
-## Graph
-
-Your coding agent answers from the compiler, spending roughly 90% fewer tokens.
+## Lint
 
-`@ttsc/graph` is an MCP server that gives the agent a compiler-resolved graph of your project: what calls what, what a change would touch, and where to start reading. The agent asks the type checker instead of grepping and re-reading files.
+Lint and format inside the type-check you already run. 720+ rules across 21 families, plus a formatter that reproduces Prettier's output.
 
-Register it with your MCP client. For Claude Code, a `.mcp.json` in the project root:
+```ts
+// src/index.ts
+var x: number = 3;
+let y: number = 4;
+const z: string = 5;
+```
 
 ```bash
-npm install -D ttsc @ttsc/graph typescript
-```
+$ npx ttsc --noEmit
+src/index.ts:3:7 - error TS2322: Type 'number' is not assignable to type 'string'.
 
-```json
-{
-  "mcpServers": {
-    "ttsc-graph": {
-      "command": "npx",
-      "args": ["-y", "@ttsc/graph"]
-    }
-  }
-}
-```
+3 const z: string = 5;
+        ~
 
-On the agent-cost benchmark, Claude agents answer reading zero files, cutting tokens by roughly 90% and tool calls by 93% to 96%. The design and per-repository numbers are in the [Code Graph guide](https://ttsc.dev/docs/graph) and the [benchmark](https://ttsc.dev/docs/benchmark/graph).
+src/index.ts:2:5 - error TS17397: [prefer-const] Use const instead of let.
 
-![Median tokens on the shared onboarding question, lower is better](https://ttsc.dev/benchmark/svg/graph-common-codex-gpt-5.6-sol.svg)
+2 let y: number = 4;
+      ~~~~~~~~~~~~~
 
-## Lint
+src/index.ts:1:1 - error TS11966: [no-var] Unexpected var, use let or const instead.
 
-Lint and format at compiler speed: up to 800x faster than ESLint.
+1 var x: number = 3;
+  ~~~~~~~~~~~~~~~~~~
 
-`@ttsc/lint` replaces ESLint and Prettier with rules that run inside the type-check. It shares one AST pass with the compiler, so linting and formatting add almost nothing to the build you already run.
+Found 3 errors in the same file, starting at: src/index.ts:3
+```
 
-Configuration is a single file. Each rule takes `"error"`, `"warning"`, or `"off"`, and the `format` block mirrors `.prettierrc`.
+Type errors and lint violations arrive in one stream, so the CI step that already runs `ttsc --noEmit` gates lint with no second job and no second parse. On vscode's 6,093 files the rules take 73 ms inside that check, where ESLint spends 66.7 s as its own command.
 
-```bash
-npm install -D @ttsc/lint
-```
+`npx ttsc fix` applies autofixes and formatting; `npx ttsc format` only formats. Rules and every `format` key are in the [Lint and Format guide](https://ttsc.dev/docs/lint).
 
-```ts
-// lint.config.ts
-import type { ITtscLintConfig } from "@ttsc/lint";
-
-export default {
-  rules: {
-    "no-var": "error",
-    "prefer-const": "error",
-    "typescript/no-explicit-any": "warning",
-  },
-  format: {
-    printWidth: 100,
-    singleQuote: true,
-    trailingComma: "all",
-  },
-} satisfies ITtscLintConfig;
+## Evidence Graph
+
+Your spec becomes a compile error, so requirement coverage is 100% or the build does not pass. An agent can still lie, but it cannot lie by omission.
+
+```tsx
+/**
+ * @evidence docs/discount.md#coupon-stacking
+ *           States the per-issuer stacking limit
+ *           this section defines, in the buyer's words.
+ * @evidence POST:/orders/{orderId}/coupons
+ *           Explains the rejection this endpoint returns
+ *           for an over-stacked coupon set.
+ * @evidence {@link hooks.useCouponStacking} Renders the limit this hook resolves.
+ */
+export function CouponStackingNotice(props: IProps): JSX.Element;
 ```
 
-Violations surface as compiler diagnostics, in the same stream as type errors, so the CI step that already runs `ttsc --noEmit` gates lint without a second job:
+`@evidence <target> <reason>` names one unit of the spec and why this declaration answers for it. A target is a document section, an API operation, a database schema model, or a TypeScript symbol as an inline link.
 
-```ts
-// src/index.ts
-var count = 3;
-let total = count;
+```bash
+$ npx ttsc
+error TS16411: [evidence/graph] Missing acknowledgement for 'docs/discount.md#coupon-stacking'
+  (Markdown H2 'Coupon Stacking' at docs/discount.md:3)
+  in Claim 1 reference 1 (markdown, symbols: h2, h3).
+
+  Use @evidence on a selected typescript host or @evidenceExclude on an eligible carrier.
+
+Found 3 errors.
 ```
 
-```text
-$ npx ttsc --noEmit
-src/index.ts:1:1 - error TS11966: [no-var] Unexpected var, use let or const instead.
+Without those tags, the build fails once per obligation, because one reference never covers another. An AI coding agent has to clear them to finish, and clearing them means citing each target and writing down why its code answers for it.
 
-1 var count = 3;
-  ~~~
+![Coverage and token spend, Plain against Evidence](https://raw.githubusercontent.com/samchon/ttsc/gh-pages/benchmark/png/evidence-summary.png)
 
-src/index.ts:2:5 - error TS17397: [prefer-const] Use const instead of let.
+## Compiler Knowledge Graph
 
-2 let total = count;
-    ~~~~~
+Your coding agent answers from the compiler instead of grepping and re-reading files.
 
-Found 2 errors in the same file, starting at: src/index.ts:1
+```json
+{
+  "mcpServers": {
+    "ttsc-graph": {
+      "command": "npx",
+      "args": ["-y", "@ttsc/graph"]
+    }
+  }
+}
 ```
 
-Clean the project in place:
+One typed MCP tool over a graph the type checker resolved: what calls what, what a change would touch, where to start reading. Answers carry names, signatures, edges, and spans, never file bodies, so a large repository cannot inflate the response.
 
-```bash
-npx ttsc fix      # lint autofixes + format edits
-npx ttsc format   # format edits only, never changes behavior
-```
+Across 64 measured question and model pairs, the median answer costs 92% fewer tokens and 95% fewer tool calls than the same agent with no MCP. The design and the comparators are in [`@ttsc/graph`](https://github.com/samchon/ttsc/tree/master/packages/graph).
 
-The rule catalog and every `format` key are in the [Lint & Format guide](https://ttsc.dev/docs/lint).
+![Median tokens on the shared onboarding question, lower is better](https://raw.githubusercontent.com/samchon/ttsc/gh-pages/benchmark/png/graph-common-codex-gpt-5.6-sol.png)
 
 ## Plugins
 
@@ -148,6 +150,7 @@ export const isStringArray = (() => {
 Utility plugins shipped in this repository:
 
 - [`@ttsc/banner`](https://github.com/samchon/ttsc/tree/master/packages/banner): adds `@packageDocumentation` JSDoc banners.
+- [`@ttsc/evidence`](https://github.com/samchon/ttsc/tree/master/packages/evidence): turns a requirement into a compile error until code, tests, or docs acknowledge it by name.
 - [`@ttsc/graph`](https://github.com/samchon/ttsc/tree/master/packages/graph): MCP server exposing a checker-resolved code graph to coding agents.
 - [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): lints and formats TypeScript source.
 - [`@ttsc/paths`](https://github.com/samchon/ttsc/tree/master/packages/paths): rewrites source path aliases so JS and declaration emit receive relative imports.

package/cmd/ttscgraph/serve.go

@@ -13,6 +13,7 @@ import (
   "slices"
   "sort"
   "strings"
+  "time"
 
   shimtsoptions "github.com/microsoft/typescript-go/shim/tsoptions"
   shimtspath "github.com/microsoft/typescript-go/shim/tspath"
@@ -45,7 +46,9 @@ const (
   serveModeUnchanged = "unchanged"
   // serveModeIncremental is edits applied onto the reused resident program.
   serveModeIncremental = "incremental"
-  // serveModeRebuild is edits applied but the program could not be reused.
+  // serveModeRebuild is edits applied but graph projection requires a complete
+  // rebuild, either because the program could not be reused or because a
+  // declaration-file boundary has no authored source shard of its own.
   serveModeRebuild = "rebuild"
   // serveModeError is a request that produced no snapshot. It is a transport
   // mode, not a computation mode: it exists so mode is never absent, because a
@@ -71,10 +74,15 @@ var serveCapabilities = fullSnapshotCapabilities
 
 type serveRequest struct {
   ID int `json:"id"`
+  // GraphSnapshotVersion opts into the incremental shard protocol. Omitted
+  // requests retain the schema-v6 full-dump response for existing
+  // @ttsc/graph clients.
+  GraphSnapshotVersion int `json:"graphSnapshotVersion,omitempty"`
 }
 
 type serveResponse struct {
-  Dump *graph.Dump `json:"dump,omitempty"`
+  Dump     *graph.Dump         `json:"dump,omitempty"`
+  Snapshot *serveGraphSnapshot `json:"snapshot,omitempty"`
   // Error is set when the request produced no snapshot; Mode is then
   // serveModeError.
   Error string `json:"error,omitempty"`
@@ -90,6 +98,8 @@ type serveResponse struct {
   Changed      bool     `json:"changed"`
 }
 
+const graphPhaseTraceEnvironment = "SAMCHON_GRAPH_TTSC_PHASE_TRACE"
+
 // newServeResponse stamps the fields every response owes the client, so no exit
 // from the serve loop can forget one.
 func newServeResponse(id int) serveResponse {
@@ -124,13 +134,17 @@ type graphSession struct {
   // generation, captured from the same parse that produced configHashes and
   // rootFiles so the published evidence and the invalidation state can never
   // describe different loads.
-  configDigests []graph.FileDigest
-  roots         []graph.RootFile
-  initialized   bool
-  // pendingDumpMode remembers a generation whose state was captured but whose
-  // dump failed. Until an input change lets the session rebuild, an unchanged
-  // request must retry that dump instead of falsely confirming the older graph.
-  pendingDumpMode string
+  configDigests           []graph.FileDigest
+  roots                   []graph.RootFile
+  initialized             bool
+  graphStore              *serveGraphStore
+  requestProtocol         int
+  requestProtocolSelected bool
+  // pending remembers a generation whose state was captured but whose selected
+  // projection failed. Until an input change lets the session rebuild, an
+  // unchanged request retries the same full or partial invalidation instead of
+  // falsely confirming the older client graph.
+  pending *graphChange
 }
 
 func newGraphSession(cwd, tsconfig string) (*graphSession, error) {
@@ -149,106 +163,187 @@ func (s *graphSession) Close() error {
 }
 
 func (s *graphSession) Snapshot() (*graph.Dump, string, bool, error) {
+  change, err := s.nextChange(false)
+  if err != nil {
+    return nil, "", false, err
+  }
+  if change == nil {
+    return nil, serveModeUnchanged, false, nil
+  }
+  dump, err := s.buildDump()
+  if err != nil {
+    s.pending = change
+    return nil, "", false, err
+  }
+  s.pending = nil
+  return &dump, change.mode, true, nil
+}
+
+type graphChange struct {
+  mode        string
+  files       []string
+  publicFiles []string
+  full        bool
+}
+
+// nextChange advances only the resident compiler and its captured input state.
+// Projection is deliberately outside this method so the legacy full-dump and
+// incremental shard protocols share exactly one invalidation decision without
+// forcing either representation onto the other.
+func (s *graphSession) nextChange(trackPublicShape bool) (*graphChange, error) {
   if !s.initialized {
     // The captured compiler state is initialized even when its first dump is
     // not publishable. Mark the attempt before building so a later request can
     // observe a config/source edit that repairs the path error instead of
     // retrying the stale Program forever.
     s.initialized = true
-    dump, err := s.buildDump()
-    if err != nil {
-      s.pendingDumpMode = serveModeInitial
-      return nil, "", false, err
-    }
-    s.pendingDumpMode = ""
-    return &dump, serveModeInitial, true, nil
+    return &graphChange{mode: serveModeInitial, full: true}, nil
   }
 
   configChanged, err := hashesChanged(s.configHashes)
   if err != nil {
-    return nil, "", false, err
+    return nil, err
   }
   if configChanged {
     if err := s.reload(); err != nil {
-      return nil, "", false, err
+      return nil, err
     }
-    return s.changedSnapshot(serveModeReload)
+    return &graphChange{mode: serveModeReload, full: true}, nil
   }
 
   if diskStatesChanged(s.auxStates) {
     if err := s.reload(); err != nil {
-      return nil, "", false, err
+      return nil, err
     }
-    return s.changedSnapshot(serveModeReload)
+    return &graphChange{mode: serveModeReload, full: true}, nil
   }
 
   roots, err := projectRootFiles(s.compiler.Program(), true)
   if err != nil {
-    return nil, "", false, err
+    return nil, err
   }
   if !slices.Equal(s.rootFiles, roots) {
     if err := s.reload(); err != nil {
-      return nil, "", false, err
+      return nil, err
     }
-    return s.changedSnapshot(serveModeReload)
+    return &graphChange{mode: serveModeReload, full: true}, nil
   }
 
   changed, deleted, err := changedSources(s.sourceHashes)
   if err != nil {
-    return nil, "", false, err
+    return nil, err
   }
   if deleted {
     if err := s.reload(); err != nil {
-      return nil, "", false, err
+      return nil, err
     }
-    return s.changedSnapshot(serveModeReload)
+    return &graphChange{mode: serveModeReload, full: true}, nil
   }
   if len(changed) == 0 {
-    if s.pendingDumpMode != "" {
-      return s.changedSnapshot(s.pendingDumpMode)
+    if s.pending != nil {
+      return s.pending, nil
     }
-    return nil, serveModeUnchanged, false, nil
+    return nil, nil
   }
   if s.compiler.Program().HasLinkedProgramPlugins() {
     if err := s.reload(); err != nil {
-      return nil, "", false, err
+      return nil, err
     }
-    return s.changedSnapshot(serveModeReload)
+    return &graphChange{mode: serveModeReload, full: true}, nil
   }
 
   mode := serveModeIncremental
+  full := false
   paths := make([]string, 0, len(changed))
   for path := range changed {
     paths = append(paths, path)
   }
   sort.Strings(paths)
+  oldShapes := make(map[string]string, len(paths))
+  for _, path := range paths {
+    source := s.compiler.Program().SourceFile(path)
+    if source == nil {
+      if err := s.reload(); err != nil {
+        return nil, err
+      }
+      return &graphChange{mode: serveModeReload, full: true}, nil
+    }
+    if source.IsDeclarationFile {
+      mode = serveModeRebuild
+      full = true
+      continue
+    }
+    if trackPublicShape {
+      shape, err := s.compiler.Program().DeclarationShapeDigest(source)
+      if err != nil {
+        return nil, err
+      }
+      oldShapes[path] = shape
+    }
+  }
   for _, path := range paths {
     if reused := s.compiler.Apply(path, changed[path]); !reused {
       mode = serveModeRebuild
+      full = true
     }
     current, exists := s.compiler.SourceText(path)
     expected := driver.ApplySourcePreambleToFile(path, changed[path], s.compiler.Program().SourcePreamble)
     if !exists || current != expected {
       if err := s.reload(); err != nil {
-        return nil, "", false, err
+        return nil, err
       }
-      return s.changedSnapshot(serveModeReload)
+      return &graphChange{mode: serveModeReload, full: true}, nil
+    }
+    source := s.compiler.Program().SourceFile(path)
+    if source == nil {
+      if err := s.reload(); err != nil {
+        return nil, err
+      }
+      return &graphChange{mode: serveModeReload, full: true}, nil
+    }
+    if source.IsDeclarationFile {
+      mode = serveModeRebuild
+      full = true
     }
   }
   if err := s.captureState(); err != nil {
-    return nil, "", false, err
+    // The compiler already accepted the edit. Preserve a full retry marker so
+    // a transient hashing/input failure cannot make the next request compare
+    // public shape against the uncommitted compiler generation and publish an
+    // incomplete closure.
+    s.pending = &graphChange{mode: serveModeRebuild, full: true}
+    return nil, err
   }
-  return s.changedSnapshot(mode)
-}
-
-func (s *graphSession) changedSnapshot(mode string) (*graph.Dump, string, bool, error) {
-  dump, err := s.buildDump()
-  if err != nil {
-    s.pendingDumpMode = mode
-    return nil, "", false, err
+  publicFiles := []string{}
+  if trackPublicShape && !full {
+    for _, path := range paths {
+      source := s.compiler.Program().SourceFile(path)
+      if source == nil {
+        return &graphChange{mode: serveModeRebuild, full: true}, nil
+      }
+      shape, err := s.compiler.Program().DeclarationShapeDigest(source)
+      if err != nil {
+        mode = serveModeRebuild
+        full = true
+        publicFiles = nil
+        break
+      }
+      if shape != oldShapes[path] {
+        publicFiles = append(publicFiles, path)
+      }
+    }
+  }
+  if s.pending != nil {
+    if s.pending.full {
+      mode = s.pending.mode
+      full = true
+      paths = nil
+    } else if !full {
+      paths = compactSortedStrings(append(paths, s.pending.files...))
+      publicFiles = compactSortedStrings(append(publicFiles, s.pending.publicFiles...))
+    }
   }
-  s.pendingDumpMode = ""
-  return &dump, mode, true, nil
+  return &graphChange{mode: mode, files: paths, publicFiles: publicFiles, full: full}, nil
 }
 
 func (s *graphSession) reload() error {
@@ -750,26 +845,86 @@ func serveSnapshots(input io.Reader, output io.Writer, cwd, tsconfig string) int
       fmt.Fprintf(stderr, "ttscgraph: unaddressable serve request: %v\n", err)
       return 1
     }
+    requestStarted := time.Now()
+    if request.GraphSnapshotVersion != 0 && request.GraphSnapshotVersion != graphSnapshotProtocolVersion {
+      if err := encodeServeResponseWithTrace(encoder, errorResponse(
+        request.ID,
+        fmt.Sprintf(
+          "ttscgraph: unsupported graph snapshot protocol v%d (supported: v%d)",
+          request.GraphSnapshotVersion,
+          graphSnapshotProtocolVersion,
+        ),
+      ), requestStarted, 0, 0, 0); err != nil {
+        fmt.Fprintf(stderr, "ttscgraph: write serve response: %v\n", err)
+        return 1
+      }
+      continue
+    }
+    var loadDuration time.Duration
     if session == nil {
+      loadStarted := time.Now()
       created, err := newGraphSession(cwd, tsconfig)
+      loadDuration = time.Since(loadStarted)
       if err != nil {
-        _ = encoder.Encode(errorResponse(request.ID, err.Error()))
+        if err := encodeServeResponseWithTrace(
+          encoder,
+          errorResponse(request.ID, err.Error()),
+          requestStarted,
+          loadDuration,
+          0,
+          0,
+        ); err != nil {
+          fmt.Fprintf(stderr, "ttscgraph: write serve response: %v\n", err)
+          return 1
+        }
         continue
       }
       session = created
     }
-    dump, mode, changed, err := session.Snapshot()
+    if session.requestProtocolSelected && session.requestProtocol != request.GraphSnapshotVersion {
+      if err := encodeServeResponseWithTrace(encoder, errorResponse(
+        request.ID,
+        "ttscgraph: graphSnapshotVersion cannot change within one resident session",
+      ), requestStarted, loadDuration, 0, 0); err != nil {
+        fmt.Fprintf(stderr, "ttscgraph: write serve response: %v\n", err)
+        return 1
+      }
+      continue
+    }
+    session.requestProtocol = request.GraphSnapshotVersion
+    session.requestProtocolSelected = true
+    var dump *graph.Dump
+    var snapshot *serveGraphSnapshot
+    var mode string
+    var changed bool
+    var semanticDuration time.Duration
+    var exportDuration time.Duration
+    var err error
+    if request.GraphSnapshotVersion == graphSnapshotProtocolVersion {
+      snapshot, mode, changed, semanticDuration, exportDuration, err = session.snapshotShardsWithTiming()
+    } else {
+      dump, mode, changed, err = session.Snapshot()
+    }
     response := newServeResponse(request.ID)
     response.Dump = dump
+    response.Snapshot = snapshot
     response.Mode = mode
     response.Changed = changed
     if err != nil {
       response.Error = err.Error()
       response.Dump = nil
+      response.Snapshot = nil
       response.Mode = serveModeError
       response.Changed = false
     }
-    if err := encoder.Encode(response); err != nil {
+    if err := encodeServeResponseWithTrace(
+      encoder,
+      response,
+      requestStarted,
+      loadDuration,
+      semanticDuration,
+      exportDuration,
+    ); err != nil {
       fmt.Fprintf(stderr, "ttscgraph: write serve response: %v\n", err)
       return 1
     }
@@ -780,3 +935,64 @@ func serveSnapshots(input io.Reader, output io.Writer, cwd, tsconfig string) int
   }
   return 0
 }
+
+// encodeServeResponseWithTrace accounts for every addressed response, including
+// failures that occur before a graph session exists.
+func encodeServeResponseWithTrace(
+  encoder *json.Encoder,
+  response serveResponse,
+  requestStarted time.Time,
+  loadDuration time.Duration,
+  semanticDuration time.Duration,
+  exportDuration time.Duration,
+) error {
+  encodeStarted := time.Now()
+  if err := encoder.Encode(response); err != nil {
+    return err
+  }
+  writeServePhaseTrace(
+    response.ID,
+    response.Mode,
+    loadDuration,
+    semanticDuration,
+    exportDuration,
+    time.Since(encodeStarted),
+    time.Since(requestStarted),
+  )
+  return nil
+}
+
+// writeServePhaseTrace emits opt-in timings without source paths or payloads.
+func writeServePhaseTrace(
+  request int,
+  mode string,
+  load time.Duration,
+  semantic time.Duration,
+  export time.Duration,
+  encode time.Duration,
+  total time.Duration,
+) {
+  if os.Getenv(graphPhaseTraceEnvironment) != "1" {
+    return
+  }
+  phases := []struct {
+    name     string
+    duration time.Duration
+  }{
+    {name: "native-load", duration: load},
+    {name: "semantic-refresh", duration: semantic},
+    {name: "shard-export", duration: export},
+    {name: "encode", duration: encode},
+    {name: "producer-total", duration: total},
+  }
+  for _, phase := range phases {
+    fmt.Fprintf(
+      stderr,
+      "@samchon/graph: ttscgraph-phase owner=producer request=%d mode=%s phase=%s durationMs=%.3f\n",
+      request,
+      mode,
+      phase.name,
+      float64(phase.duration)/float64(time.Millisecond),
+    )
+  }
+}