@telorun/sdk 0.68.0 → 0.70.0

package/dist/bigint-json.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reading a wide integer back out of a `JSON.stringify` replacer.
+ *
+ * CEL models `int` as int64, which this runtime evaluates to a JS BigInt — so
+ * `size(group)`, `sum(...)` and integer arithmetic all produce one, and the kernel
+ * installs `BigInt.prototype.toJSON` at boot (`enableBigIntJson`,
+ * `kernel/nodejs/src/bigint-json.ts`) so every JSON boundary in the process emits
+ * it as its exact decimal digits.
+ *
+ * The installer is a composition-root action and lives in the kernel. What a
+ * MODULE AUTHOR needs is the consequence, which is what this file carries: a
+ * `toJSON` runs BEFORE a replacer, so a sink or codec that must encode a wide
+ * integer differently from the process default can no longer recognise one by
+ * `typeof`.
+ */
+/** The process-global flag {@link isBigIntJsonEnabled} reads and the kernel's
+ *  installer sets. Shared through `Symbol.for` so a second `@telorun/sdk` copy in
+ *  the process (the test suite runs child kernels in-process) sees the first
+ *  install rather than re-wrapping. */
+export declare const BIGINT_JSON_INSTALLED_KEY: symbol;
+/** True once the kernel has installed `BigInt.prototype.toJSON` in this process. */
+export declare function isBigIntJsonEnabled(): boolean;
+/**
+ * The BigInt a `JSON.stringify` replacer was called for, or `undefined` when the
+ * value is not one.
+ *
+ * `JSON.stringify` applies `toJSON` BEFORE the replacer, so once the patch is
+ * installed a replacer never sees a `bigint` — it sees the opaque raw-JSON token.
+ * A serializer that wants a DIFFERENT encoding than the exact digits (OTLP quotes
+ * its 64-bit fields; a round-trippable store tags them; a console encoding renders
+ * them as text) has to reach past the token, and `JSON.stringify` hands it the
+ * means: the replacer is called with the holder as `this`, and the holder still
+ * has the original value.
+ *
+ * Reading the holder also makes the result independent of whether the patch is
+ * installed, so an encoder called outside a booted kernel behaves identically.
+ *
+ * Only reach for this when the default is genuinely wrong for the destination.
+ * Everything that wants exact digits on the wire needs no replacer at all.
+ */
+export declare function bigIntAt(holder: unknown, key: string): bigint | undefined;
+//# sourceMappingURL=bigint-json.d.ts.map

package/dist/bigint-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigint-json.d.ts","sourceRoot":"","sources":["../src/bigint-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;uCAGuC;AACvC,eAAO,MAAM,yBAAyB,QAAgB,CAAC;AAEvD,oFAAoF;AACpF,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE"}

package/dist/bigint-json.js

@@ -0,0 +1,47 @@
+/**
+ * Reading a wide integer back out of a `JSON.stringify` replacer.
+ *
+ * CEL models `int` as int64, which this runtime evaluates to a JS BigInt — so
+ * `size(group)`, `sum(...)` and integer arithmetic all produce one, and the kernel
+ * installs `BigInt.prototype.toJSON` at boot (`enableBigIntJson`,
+ * `kernel/nodejs/src/bigint-json.ts`) so every JSON boundary in the process emits
+ * it as its exact decimal digits.
+ *
+ * The installer is a composition-root action and lives in the kernel. What a
+ * MODULE AUTHOR needs is the consequence, which is what this file carries: a
+ * `toJSON` runs BEFORE a replacer, so a sink or codec that must encode a wide
+ * integer differently from the process default can no longer recognise one by
+ * `typeof`.
+ */
+const INSTALLED_KEY = Symbol.for("@telorun/sdk:bigint-json:installed");
+/** The process-global flag {@link isBigIntJsonEnabled} reads and the kernel's
+ *  installer sets. Shared through `Symbol.for` so a second `@telorun/sdk` copy in
+ *  the process (the test suite runs child kernels in-process) sees the first
+ *  install rather than re-wrapping. */
+export const BIGINT_JSON_INSTALLED_KEY = INSTALLED_KEY;
+/** True once the kernel has installed `BigInt.prototype.toJSON` in this process. */
+export function isBigIntJsonEnabled() {
+    return globalThis[INSTALLED_KEY] === true;
+}
+/**
+ * The BigInt a `JSON.stringify` replacer was called for, or `undefined` when the
+ * value is not one.
+ *
+ * `JSON.stringify` applies `toJSON` BEFORE the replacer, so once the patch is
+ * installed a replacer never sees a `bigint` — it sees the opaque raw-JSON token.
+ * A serializer that wants a DIFFERENT encoding than the exact digits (OTLP quotes
+ * its 64-bit fields; a round-trippable store tags them; a console encoding renders
+ * them as text) has to reach past the token, and `JSON.stringify` hands it the
+ * means: the replacer is called with the holder as `this`, and the holder still
+ * has the original value.
+ *
+ * Reading the holder also makes the result independent of whether the patch is
+ * installed, so an encoder called outside a booted kernel behaves identically.
+ *
+ * Only reach for this when the default is genuinely wrong for the destination.
+ * Everything that wants exact digits on the wire needs no replacer at all.
+ */
+export function bigIntAt(holder, key) {
+    const source = holder?.[key];
+    return typeof source === "bigint" ? source : undefined;
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./bigint-json.js";
 export * from "./cancellation.js";
 export * from "./compiled-value.js";
 export * from "./capabilities/invokable.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./bigint-json.js";
 export * from "./cancellation.js";
 export * from "./compiled-value.js";
 export * from "./capabilities/invokable.js";

package/dist/json-value.d.ts

@@ -1,17 +1,16 @@
 /**
  * JSON encoding for values that cross a persistence boundary.
  *
- * `JSON.stringify` THROWS on a BigInt, and CEL integers surface as BigInt in
- * this runtime — so any controller that persists a result computed in CEL
- * (`{ charged: 500 }` from a `Run.Sequence` output) hits it. A store that lets
- * that throw escape is worse than one that never persisted: the caller sees an
- * opaque TypeError, and a decorator built on the store can mistake it for the
- * body having failed.
+ * BigInt is encoded as a tagged object rather than as a plain string, a Number,
+ * or the exact digits every other JSON boundary emits: this codec has to be
+ * INVERTIBLE. A replayed value must equal the freshly-produced one — including
+ * its type — or at-most-once execution silently changes its answer on the second
+ * call. Digits would come back as a Number (lossy past 2^53), a string would come
+ * back a different type than went in.
  *
- * BigInt is encoded as a tagged object rather than a plain string or a Number:
- * a string would come back a different type than went in, and Number is lossy
- * past 2^53. A replayed value must equal the freshly-produced one, or
- * at-most-once execution silently changes its answer on the second call.
+ * That is why this file reaches past `BigInt.prototype.toJSON` with
+ * {@link bigIntAt} instead of inheriting the process-wide encoding: the wire wants
+ * the value, a store wants the value AND its type back.
  */
 /** Serialize a value to JSON text, preserving BigInt exactly. */
 export declare function encodeJsonValue(value: unknown): string;

package/dist/json-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-value.d.ts","sourceRoot":"","sources":["../src/json-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAItD;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}
+{"version":3,"file":"json-value.d.ts","sourceRoot":"","sources":["../src/json-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoBH,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKtD;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/json-value.js

@@ -1,18 +1,18 @@
 /**
  * JSON encoding for values that cross a persistence boundary.
  *
- * `JSON.stringify` THROWS on a BigInt, and CEL integers surface as BigInt in
- * this runtime — so any controller that persists a result computed in CEL
- * (`{ charged: 500 }` from a `Run.Sequence` output) hits it. A store that lets
- * that throw escape is worse than one that never persisted: the caller sees an
- * opaque TypeError, and a decorator built on the store can mistake it for the
- * body having failed.
+ * BigInt is encoded as a tagged object rather than as a plain string, a Number,
+ * or the exact digits every other JSON boundary emits: this codec has to be
+ * INVERTIBLE. A replayed value must equal the freshly-produced one — including
+ * its type — or at-most-once execution silently changes its answer on the second
+ * call. Digits would come back as a Number (lossy past 2^53), a string would come
+ * back a different type than went in.
  *
- * BigInt is encoded as a tagged object rather than a plain string or a Number:
- * a string would come back a different type than went in, and Number is lossy
- * past 2^53. A replayed value must equal the freshly-produced one, or
- * at-most-once execution silently changes its answer on the second call.
+ * That is why this file reaches past `BigInt.prototype.toJSON` with
+ * {@link bigIntAt} instead of inheriting the process-wide encoding: the wire wants
+ * the value, a store wants the value AND its type back.
  */
+import { bigIntAt } from "./bigint-json.js";
 const BIGINT_TAG = "$bigint";
 function isTaggedBigInt(value) {
     return (typeof value === "object" &&
@@ -23,7 +23,10 @@ function isTaggedBigInt(value) {
 }
 /** Serialize a value to JSON text, preserving BigInt exactly. */
 export function encodeJsonValue(value) {
-    return JSON.stringify(value ?? null, (_k, v) => typeof v === "bigint" ? { [BIGINT_TAG]: v.toString() } : v);
+    return JSON.stringify(value ?? null, function (key, v) {
+        const source = bigIntAt(this, key);
+        return source === undefined ? v : { [BIGINT_TAG]: source.toString() };
+    });
 }
 /** Inverse of {@link encodeJsonValue}; BigInt values are restored as BigInt. */
 export function decodeJsonValue(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/bigint-json.ts

@@ -0,0 +1,51 @@
+/**
+ * Reading a wide integer back out of a `JSON.stringify` replacer.
+ *
+ * CEL models `int` as int64, which this runtime evaluates to a JS BigInt — so
+ * `size(group)`, `sum(...)` and integer arithmetic all produce one, and the kernel
+ * installs `BigInt.prototype.toJSON` at boot (`enableBigIntJson`,
+ * `kernel/nodejs/src/bigint-json.ts`) so every JSON boundary in the process emits
+ * it as its exact decimal digits.
+ *
+ * The installer is a composition-root action and lives in the kernel. What a
+ * MODULE AUTHOR needs is the consequence, which is what this file carries: a
+ * `toJSON` runs BEFORE a replacer, so a sink or codec that must encode a wide
+ * integer differently from the process default can no longer recognise one by
+ * `typeof`.
+ */
+
+const INSTALLED_KEY = Symbol.for("@telorun/sdk:bigint-json:installed");
+
+/** The process-global flag {@link isBigIntJsonEnabled} reads and the kernel's
+ *  installer sets. Shared through `Symbol.for` so a second `@telorun/sdk` copy in
+ *  the process (the test suite runs child kernels in-process) sees the first
+ *  install rather than re-wrapping. */
+export const BIGINT_JSON_INSTALLED_KEY = INSTALLED_KEY;
+
+/** True once the kernel has installed `BigInt.prototype.toJSON` in this process. */
+export function isBigIntJsonEnabled(): boolean {
+  return (globalThis as Record<symbol, unknown>)[INSTALLED_KEY] === true;
+}
+
+/**
+ * The BigInt a `JSON.stringify` replacer was called for, or `undefined` when the
+ * value is not one.
+ *
+ * `JSON.stringify` applies `toJSON` BEFORE the replacer, so once the patch is
+ * installed a replacer never sees a `bigint` — it sees the opaque raw-JSON token.
+ * A serializer that wants a DIFFERENT encoding than the exact digits (OTLP quotes
+ * its 64-bit fields; a round-trippable store tags them; a console encoding renders
+ * them as text) has to reach past the token, and `JSON.stringify` hands it the
+ * means: the replacer is called with the holder as `this`, and the holder still
+ * has the original value.
+ *
+ * Reading the holder also makes the result independent of whether the patch is
+ * installed, so an encoder called outside a booted kernel behaves identically.
+ *
+ * Only reach for this when the default is genuinely wrong for the destination.
+ * Everything that wants exact digits on the wire needs no replacer at all.
+ */
+export function bigIntAt(holder: unknown, key: string): bigint | undefined {
+  const source = (holder as Record<string, unknown> | null | undefined)?.[key];
+  return typeof source === "bigint" ? source : undefined;
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./bigint-json.js";
 export * from "./cancellation.js";
 export * from "./compiled-value.js";
 export * from "./capabilities/invokable.js";

package/src/json-value.ts

@@ -1,19 +1,20 @@
 /**
  * JSON encoding for values that cross a persistence boundary.
  *
- * `JSON.stringify` THROWS on a BigInt, and CEL integers surface as BigInt in
- * this runtime — so any controller that persists a result computed in CEL
- * (`{ charged: 500 }` from a `Run.Sequence` output) hits it. A store that lets
- * that throw escape is worse than one that never persisted: the caller sees an
- * opaque TypeError, and a decorator built on the store can mistake it for the
- * body having failed.
+ * BigInt is encoded as a tagged object rather than as a plain string, a Number,
+ * or the exact digits every other JSON boundary emits: this codec has to be
+ * INVERTIBLE. A replayed value must equal the freshly-produced one — including
+ * its type — or at-most-once execution silently changes its answer on the second
+ * call. Digits would come back as a Number (lossy past 2^53), a string would come
+ * back a different type than went in.
  *
- * BigInt is encoded as a tagged object rather than a plain string or a Number:
- * a string would come back a different type than went in, and Number is lossy
- * past 2^53. A replayed value must equal the freshly-produced one, or
- * at-most-once execution silently changes its answer on the second call.
+ * That is why this file reaches past `BigInt.prototype.toJSON` with
+ * {@link bigIntAt} instead of inheriting the process-wide encoding: the wire wants
+ * the value, a store wants the value AND its type back.
  */
 
+import { bigIntAt } from "./bigint-json.js";
+
 const BIGINT_TAG = "$bigint";
 
 interface TaggedBigInt {
@@ -32,9 +33,10 @@ function isTaggedBigInt(value: unknown): value is TaggedBigInt {
 
 /** Serialize a value to JSON text, preserving BigInt exactly. */
 export function encodeJsonValue(value: unknown): string {
-  return JSON.stringify(value ?? null, (_k, v) =>
-    typeof v === "bigint" ? { [BIGINT_TAG]: v.toString() } : v,
-  );
+  return JSON.stringify(value ?? null, function (this: unknown, key, v) {
+    const source = bigIntAt(this, key);
+    return source === undefined ? v : { [BIGINT_TAG]: source.toString() };
+  });
 }
 
 /** Inverse of {@link encodeJsonValue}; BigInt values are restored as BigInt. */