@shipeasy/sdk 4.5.0 → 5.0.0

package/README.md

@@ -69,12 +69,12 @@ try {
 }
 
 // Non-exception problems — the name is a stable identifier (it participates
-// in the issue fingerprint); variable data goes in .message() / .extras():
+// in the issue fingerprint); all variable data goes in .extras():
 if (rows.length > LIMIT) {
   see.Violation("large query")
-    .message(`got ${rows.length} rows`)
     .causes_the("search results")
-    .to("be trimmed");
+    .to("be trimmed")
+    .extras({ rows: rows.length });
 }
 
 // Expected control-flow exceptions: document them, report nothing —
@@ -82,7 +82,7 @@ if (rows.length > LIMIT) {
 try {
   return decodeFoo(blob);
 } catch (e) {
-  see.ControlFlowException(e, "because it wasn't an encoded Foo");
+  see.ControlFlowException(e).because("because it wasn't an encoded Foo");
   return decodeBar(blob);
 }
 ```
@@ -94,16 +94,19 @@ occurrence timeseries. The chain dispatches on the next microtask — no
 `fetch` on the server), spam-guarded by a 30s dedup window and a per-session
 cap.
 
-The client SDK also auto-captures uncaught exceptions, unhandled rejections,
-and network failures (fetch network errors + 5xx) into the same primitive
-(`autoCollect: { errors }`, on by default). Auto-capture is the outer safety
-net — it does not replace `see()` in catch blocks, where you know the
-consequence and it cannot.
-
-**Rules**: if you don't know the consequence, don't catch the exception. Never
-`see()` then `throw` (double counting — either handle or rethrow). Never use
-`see.Violation()` for a caught exception (you'd drop the stack). No PII or
-high-cardinality data in extras.
+The client SDK also auto-captures **network failures** (fetch network errors +
+5xx) into the same primitive (`autoCollect: { errors }`, on by default) — each
+names a specific endpoint and a specific outcome. It deliberately does **not**
+blanket-report uncaught exceptions or unhandled promise rejections: those carry
+no actionable consequence ("the page hit an error" names the plumbing, not the
+feature). Code that knows the consequence reports it explicitly with `see()` at
+the catch site.
+
+**Rules**: if you don't know the consequence, don't catch the exception. You
+**may** `see()` then re-throw — the re-thrown error links to its inner report
+as a `caused_by` chain instead of double-counting. Never use `see.Violation()`
+for a caught exception (you'd drop the stack). No PII or high-cardinality data
+in extras.
 
 ## Drop-in `<script>` loader (no bundler)
 

package/dist/client/index.d.mts

@@ -8,15 +8,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -84,9 +82,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare global {
@@ -430,28 +441,29 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (rows.length > LIMIT) {
-     *   see.Violation("large query").message(`got ${rows.length} rows`)
-     *      .causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: rows.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — auto-capture skips it and
-     * nothing is reported. The reason must start with "because".
+     * nothing is reported. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
      *
      * ```ts
      * } catch (e) {
-     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   see.ControlFlowException(e).because("because the blob wasn't an encoded Foo");
      *   return decodeAsBar(blob);
      * }
      * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -497,4 +509,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -8,15 +8,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -84,9 +82,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare global {
@@ -430,28 +441,29 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (rows.length > LIMIT) {
-     *   see.Violation("large query").message(`got ${rows.length} rows`)
-     *      .causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: rows.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — auto-capture skips it and
-     * nothing is reported. The reason must start with "because".
+     * nothing is reported. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
      *
      * ```ts
      * } catch (e) {
-     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   see.ControlFlowException(e).because("because the blob wasn't an encoded Foo");
      *   return decodeAsBar(blob);
      * }
      * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -497,4 +509,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.js

@@ -126,25 +126,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -225,7 +229,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -308,19 +312,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -575,39 +581,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     }
   }
   if (groups.errors) {
-    const origOnError = window.onerror;
-    window.onerror = (msg, source, lineno, _colno, err) => {
-      if (!isExpected(err)) {
-        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
-        reportSee(
-          problem,
-          causesThe("page").to("hit an unhandled error"),
-          {
-            source: typeof source === "string" ? source : void 0,
-            line: lineno ?? void 0
-          },
-          "uncaught"
-        );
-      }
-      if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
-      return false;
-    };
-    window.addEventListener("unhandledrejection", (e) => {
-      const reason = e.reason;
-      if (isExpected(reason)) return;
-      reportSee(
-        reason ?? "Unhandled promise rejection",
-        causesThe("page").to("hit an unhandled promise rejection"),
-        void 0,
-        "unhandled_rejection"
-      );
-    });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
       const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
-      const bareUrl = url.split("?")[0].slice(0, 200);
       let corr;
       if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
         corr = crypto.randomUUID();
@@ -619,7 +597,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       } catch (err) {
         if (!ignored && !isExpected(err)) {
           reportSee(
-            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            violation("NetworkError"),
             causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
@@ -630,7 +608,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
-          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          violation("Http5xx"),
           causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
           "network",
@@ -1409,7 +1387,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 var LABEL_MARKER_START = "\uFFF9";

package/dist/client/index.mjs

@@ -78,25 +78,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -177,7 +181,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -260,19 +264,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -527,39 +533,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     }
   }
   if (groups.errors) {
-    const origOnError = window.onerror;
-    window.onerror = (msg, source, lineno, _colno, err) => {
-      if (!isExpected(err)) {
-        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
-        reportSee(
-          problem,
-          causesThe("page").to("hit an unhandled error"),
-          {
-            source: typeof source === "string" ? source : void 0,
-            line: lineno ?? void 0
-          },
-          "uncaught"
-        );
-      }
-      if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
-      return false;
-    };
-    window.addEventListener("unhandledrejection", (e) => {
-      const reason = e.reason;
-      if (isExpected(reason)) return;
-      reportSee(
-        reason ?? "Unhandled promise rejection",
-        causesThe("page").to("hit an unhandled promise rejection"),
-        void 0,
-        "unhandled_rejection"
-      );
-    });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
       const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
-      const bareUrl = url.split("?")[0].slice(0, 200);
       let corr;
       if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
         corr = crypto.randomUUID();
@@ -571,7 +549,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       } catch (err) {
         if (!ignored && !isExpected(err)) {
           reportSee(
-            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            violation("NetworkError"),
             causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
@@ -582,7 +560,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
-          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          violation("Http5xx"),
           causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
           "network",
@@ -1361,7 +1339,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 var LABEL_MARKER_START = "\uFFF9";

package/dist/server/index.d.mts

@@ -10,15 +10,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -87,9 +85,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare const version = "4.0.0";
@@ -367,20 +378,26 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (results.length > LIMIT) {
-     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: results.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — documents the expectation and
-     * reports nothing. The reason must start with "because".
+     * reports nothing. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
+     *
+     * ```ts
+     * see.ControlFlowException(e).because("because the metric may not exist yet");
+     * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -389,4 +406,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -10,15 +10,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -87,9 +85,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare const version = "4.0.0";
@@ -367,20 +378,26 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (results.length > LIMIT) {
-     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: results.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — documents the expectation and
-     * reports nothing. The reason must start with "because".
+     * reports nothing. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
+     *
+     * ```ts
+     * see.ControlFlowException(e).because("because the metric may not exist yet");
+     * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -389,4 +406,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.js

@@ -128,25 +128,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -227,7 +231,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -310,19 +314,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -1027,7 +1033,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 // Annotate the CommonJS export names for ESM import in node:

package/dist/server/index.mjs

@@ -81,25 +81,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -180,7 +184,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -263,19 +267,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -980,7 +986,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "4.5.0",
+  "version": "5.0.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",