@glasstrace/sdk 1.15.1 → 1.17.0

package/README.md

@@ -580,9 +580,9 @@ Values are bounded to identifier-shaped compact tokens, with
 specialized BCP-47 validation for `locale` and IANA validation for
 `timezone`.
 
-**Open pattern** (4 canonical suffixes): keys matching
-`^[a-z][A-Za-z0-9]*(Class|Count|Kind|Role)$` are admitted alongside
-the stable core. Value shapes are suffix-routed:
+**Open pattern** (5 canonical suffixes): keys matching
+`^[a-z][A-Za-z0-9]*(Class|Count|Kind|Role|Holds)$` are admitted
+alongside the stable core. Value shapes are suffix-routed:
 
 | Suffix | Value shape | Max length | Casing convention | Examples |
 |---|---|---|---|---|
@@ -590,6 +590,7 @@ the stable core. Value shapes are suffix-routed:
 | `*Count` | non-negative integer string | 16 | digits only (no `-`, `.`, or letters) | `participantCount="2"`, `attemptCount="3"` |
 | `*Kind` | identifier-shaped compact token | 80 | lowerCamel or `UPPERCASE-CONST` | `notificationKind=transactional` |
 | `*Role` | identifier-shaped compact token | 80 | lowercase-kebab | `actorRole=operator` |
+| `*Holds` | boolean-literal string | 5 | `"true"` / `"false"` only | `timezonePreservedHolds="false"` (see [Boolean relations](#boolean-relations-holds)) |
 
 Value casing is preserved verbatim; normalize at the call site so
 cross-trace comparisons collapse to the same identity. Non-digit
@@ -670,6 +671,103 @@ ingestion service before persistence. This is intentional
 defense-in-depth: the SDK is the first gate; the product receiver
 is the second.
 
+### Value-fidelity scalars
+
+Beyond the categorical `fields` channel, `recordSideEffect()` accepts an
+optional `scalars` map for type-aware magnitudes emitted on a separate
+`glasstrace.side_effect.scalar.*` channel. The key suffix declares the
+value type:
+
+- `*Ms` / `*Amount` / `*Bytes` / `*Ratio` / `*Value` → a finite `number`
+- `*Flag` → a `boolean`
+- `*Id` → a pseudonymized `gthid_` string (see `hashId` below)
+
+(`Count` stays on the categorical `fields` channel; free-form string
+enums belong there too, not on the scalar channel.)
+
+```ts
+import { recordSideEffect } from "@glasstrace/sdk";
+import { hashId } from "@glasstrace/sdk/node";
+
+recordSideEffect({
+  kind: "external_api",
+  operation: "charge.create",
+  status: "succeeded",
+  scalars: {
+    latencyMs: 142, // bounded delta — not a wall-clock epoch
+    amountValue: 1999, // a magnitude
+    retriedFlag: false, // a boolean condition
+    // Identifiers must be pseudonymized; raw ids are rejected.
+    customerId: hashId(rawCustomerId, process.env.GLASSTRACE_ATTR_HMAC_KEY!),
+  },
+});
+```
+
+Scalars are validated at emit time under a **fail-closed `strict`**
+posture. (An account-level `captureFidelity` setting that can relax the
+timestamp/identifier rejections is part of the wire contract but is **not
+active in this release** — scalars are always validated as `strict`
+here.) Under `strict` the SDK rejects values that would leak raw,
+high-cardinality data before they reach the wire, recording only an
+integer omission count:
+
+| Rejected value | Omission reason |
+|---|---|
+| A `Date`, or a raw epoch on a `*Ms` key | `raw_timestamp` |
+| A non-`gthid_` value on an `*Id` key | `unhashed_id` |
+| `NaN` / `±Infinity` | `non_finite` |
+| A value whose type doesn't match its key suffix (e.g. a string or boolean on `*Ms`) | `raw_payload` |
+| A key not matching the scalar pattern | `unsupported_key` |
+| More than 16 scalars in one call (the excess are dropped) | `value_too_long` |
+
+Send **bounded deltas as numbers** (e.g. `latencyMs: 142`), not absolute
+timestamps. Note that raw-epoch screening applies only to `*Ms` keys (the
+time-typed suffix) — keep wall-clock values off other numeric suffixes.
+Pseudonymize identifiers with **`hashId`** (HMAC-SHA256, fixed-shape
+`gthid_<hex>`, fail-closed — returns `null` without a key), which ships on
+the Node-only `@glasstrace/sdk/node` subpath because it uses
+`node:crypto`. At most 16 scalars are recorded per operation.
+
+### Boolean relations (`*Holds`)
+
+When the decisive evidence is a *relationship* between values rather than
+the values themselves, emit it as a boolean **relation** on the
+categorical field channel. `recordSideEffect()` accepts a `relations` map
+of `boolean`s keyed by camelCase names ending in `Holds`; values are
+coerced to `"true"`/`"false"`:
+
+> **Availability:** the SDK emits `*Holds` relations now, but the Glasstrace
+> backend admits them only once a coordinated release lands; until then a
+> `*Holds` field is dropped at ingestion (like any unrecognized key) and is
+> not yet surfaced in traces. Capture is also gated by the account
+> `sideEffectEvidence` flag.
+
+```ts
+import { recordSideEffect, invariant, isNullInvariant } from "@glasstrace/sdk";
+
+recordSideEffect({
+  kind: "calendar_link",
+  operation: "invite.create",
+  relations: {
+    // Did the emitted duration match what was declared?
+    durationMatchesHolds: invariant(emittedMinutes, "eq", declaredMinutes),
+    // Was the timezone preserved (not silently dropped)?
+    timezonePreservedHolds: invariant(emittedTz, "eq", declaredTz),
+    recipientMissingHolds: isNullInvariant(recipient),
+  },
+});
+```
+
+`invariant(left, op, right)` evaluates one of `eq` / `neq` / `lt` / `lte`
+/ `gt` / `gte` and returns the boolean; `isNullInvariant(value)` is the
+unary `null`/`undefined` check. Both are pure and edge-safe (root barrel).
+
+A relation key not ending in `Holds`, a non-boolean value, or a key
+already attached by `fields` (a same-channel collision — `fields` takes
+precedence) is dropped and recorded only as an integer omission count.
+Relations count against the same product-side per-operation field budget
+as `fields` (enforced at projection).
+
 ## Source maps
 
 Glasstrace uploads server-side source maps at build time and resolves
@@ -841,7 +939,7 @@ without a deprecation cycle. Rely on the static file.
 
 ## Subpath exports
 
-`@glasstrace/sdk` ships four public entries:
+`@glasstrace/sdk` ships six public entries:
 
 - **`@glasstrace/sdk`** — primary import site. Use from
   `instrumentation.ts` (runtime instrumentation) and `next.config.ts`
@@ -853,14 +951,19 @@ without a deprecation cycle. Rely on the static file.
   runtimes; workloads running strictly on workerd or Vercel Edge
   should import from the internal edge-entry bundle — not currently
   exposed as a public entry — or ask for a public `/edge` subpath.
-- **`@glasstrace/sdk/node`** — Node-only build-time tooling
-  (source-map uploading, import-graph construction). Use from
-  `next.config.ts` / build scripts. Resolves only under the Node
-  condition; non-Node runtimes (workerd, edge-light) fail cleanly at
-  module resolution rather than at evaluation.
+- **`@glasstrace/sdk/node`** — Node-only helpers: build-time tooling
+  (source-map uploading, import-graph construction) plus the request-time
+  `hashId` identifier-pseudonymization helper for value-fidelity scalars.
+  Resolves only under the Node condition; non-Node runtimes (workerd,
+  edge-light) fail cleanly at module resolution rather than at
+  evaluation.
 - **`@glasstrace/sdk/drizzle`** — Drizzle ORM adapter.
 - **`@glasstrace/sdk/trpc`** — tRPC middleware-chain instrumentation.
   See "tRPC middleware instrumentation" below.
+- **`@glasstrace/sdk/middleware`** — request-middleware tracing wrapper
+  (`tracedRequestMiddleware`).
+- **`@glasstrace/sdk/async-context`** — async causality propagation
+  (`withAsyncCausality`).
 
 The source-map and import-graph helpers previously reachable from the
 `@glasstrace/sdk` root specifier have moved to `@glasstrace/sdk/node`
@@ -906,11 +1009,15 @@ and the recommended call site.
 | `discoverTestFiles` | function | `node:fs`, `node:path` | — (call from a build script / CI job) |
 | `extractImports` | function | — (pure string processing) | — (kept under `/node` for API cohesion with `buildImportGraph`) |
 | `buildImportGraph` | function | `node:fs`, `node:path`, `node:crypto` | — (call from a build script / CI job) |
+| `hashId` | function | `node:crypto` | — (call from the request handler that records the side effect) |
 
 Type exports erase at runtime and are technically safe to import from
 edge code, but every runtime function that produces or consumes them is
-Node-only, so the practical signal is the same: reach for these from
-your build pipeline, not from a request handler.
+Node-only, so the practical signal is the same: reach for the source-map
+and import-graph helpers from your build pipeline, not from a request
+handler. `hashId` is the exception — it is a request-time helper for
+pseudonymizing identifiers before `recordSideEffect()`, Node-only only
+because it uses `node:crypto`.
 
 #### Why is X Node-only?
 

package/dist/async-context/index.cjs

@@ -15297,7 +15297,20 @@ var CaptureConfigSchema = external_exports.object({
    * client-side allowlist enforcement layered with the product's
    * storage-time filter as defense-in-depth.
    */
-  sideEffectEvidence: external_exports.boolean().optional().default(false)
+  sideEffectEvidence: external_exports.boolean().optional().default(false),
+  /**
+   * Per-account value-fidelity capture posture (server-pushed).
+   *
+   * `strict` (default) is fail-closed: the SDK rejects raw wall-clock
+   * timestamps and unhashed identifiers from the `scalar.*` channel at
+   * emit time. `full` relaxes those rejections so raw magnitudes can be
+   * surfaced — but only in conjunction with an explicit producer opt-in
+   * (so a `full`-configured account still emits strict-shaped scalars
+   * unless the producer also opts in). The operator owns this flag; it
+   * is never derived from producer or request input. Absent on the wire
+   * ⇒ `strict`.
+   */
+  captureFidelity: external_exports.enum(["strict", "full"]).optional().default("strict")
 });
 var SdkCachedConfigSchema = external_exports.object({
   response: external_exports.record(external_exports.string(), external_exports.unknown()),
@@ -15488,7 +15501,13 @@ var GLASSTRACE_ATTRIBUTE_NAMES = {
   SIDE_EFFECT_OMITTED_UNSUPPORTED_KEY: "glasstrace.side_effect.omitted.unsupported_key",
   SIDE_EFFECT_OMITTED_VALUE_TOO_LONG: "glasstrace.side_effect.omitted.value_too_long",
   SIDE_EFFECT_OMITTED_NOT_EMITTED: "glasstrace.side_effect.omitted.not_emitted",
-  SIDE_EFFECT_OMITTED_CAPTURE_DISABLED: "glasstrace.side_effect.omitted.capture_disabled"
+  SIDE_EFFECT_OMITTED_CAPTURE_DISABLED: "glasstrace.side_effect.omitted.capture_disabled",
+  // Value-fidelity scalar-channel omission reasons. Counts only; the
+  // rejected raw value (timestamp, unhashed id, non-finite number) is
+  // never echoed. Mirror the product omission enum verbatim.
+  SIDE_EFFECT_OMITTED_RAW_TIMESTAMP: "glasstrace.side_effect.omitted.raw_timestamp",
+  SIDE_EFFECT_OMITTED_UNHASHED_ID: "glasstrace.side_effect.omitted.unhashed_id",
+  SIDE_EFFECT_OMITTED_NON_FINITE: "glasstrace.side_effect.omitted.non_finite"
 };
 var MAX_SOURCE_MAP_FILE_PATH_LENGTH = 512;
 var MAX_SOURCE_MAP_FILE_SIZE = 50 * 1024 * 1024;