@substrat-run/contracts 0.149.0 → 0.151.0

package/dist/trace-sink.js

@@ -0,0 +1,50 @@
+/** The `globalThis` slot a host reads its sink from. A registered symbol, so two copies of a package agree. */
+export const TRACE_SINK_KEY = Symbol.for('substrat.trace-sink');
+/** The most steps one trace keeps; later ones are counted in `stepsDropped`, not stored. */
+export const TRACE_STEP_CAP = 500;
+/** The step kinds, in the order a reader lists them. */
+export const TRACE_STEP_TYPES = [
+    'check',
+    'sql',
+    'emit',
+    'log',
+    'validation',
+    'outbound',
+    'store',
+    'error',
+];
+/**
+ * One time axis per invocation, shared by whoever records a step.
+ *
+ * The HTTP layer starts the request and the scope host runs inside it, so each used to count
+ * from its own zero and a step from one could sort before the step that caused it. The layer
+ * that starts the request calls {@link markTraceStart}; every step is stamped with
+ * {@link traceOffsetMs}, which counts from that mark, or from its own first call when nothing
+ * marked one (a call that did not come through HTTP). {@link forgetTraceStart} releases it.
+ * Held on a `globalThis` slot, like the sink, so two copies of a package agree.
+ */
+const STARTS_KEY = Symbol.for('substrat.trace-starts');
+function starts() {
+    const slots = globalThis;
+    return (slots[STARTS_KEY] ??= new Map());
+}
+/** Note that an invocation started now (or at `at`, on the `performance.now()` clock). */
+export function markTraceStart(invocationId, at = performance.now()) {
+    const map = starts();
+    if (!map.has(invocationId))
+        map.set(invocationId, at);
+}
+/** Milliseconds since the invocation started, starting it now when nothing has. */
+export function traceOffsetMs(invocationId) {
+    markTraceStart(invocationId);
+    return Math.max(0, Math.round(performance.now() - starts().get(invocationId)));
+}
+/** The invocation is over: release its start. */
+export function forgetTraceStart(invocationId) {
+    starts().delete(invocationId);
+}
+/** The sink installed on this runtime, or `undefined` when tracing is off. */
+export function installedTraceSink() {
+    return globalThis[TRACE_SINK_KEY];
+}
+//# sourceMappingURL=trace-sink.js.map

package/dist/trace-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sink.js","sourceRoot":"","sources":["../src/trace-sink.ts"],"names":[],"mappings":"AA0BA,+GAA+G;AAC/G,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAU,CAAC;AAExF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,wDAAwD;AACxD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO;IACP,KAAK;IACL,MAAM;IACN,KAAK;IACL,YAAY;IACZ,UAAU;IACV,OAAO;IACP,OAAO;CACC,CAAC;AAkLX;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAkB,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAU,CAAC;AAE/E,SAAS,MAAM;IACb,MAAM,KAAK,GAAG,UAAqC,CAAC;IACpD,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,IAAI,GAAG,EAAkB,CAAwB,CAAC;AAClF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,EAAE,GAAW,WAAW,CAAC,GAAG,EAAE;IACjF,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,YAAoB;IAChD,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,YAAY,CAAE,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,gBAAgB,CAAC,YAAoB;IACnD,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB;IAChC,OAAQ,UAAsC,CAAC,cAAc,CAA0B,CAAC;AAC1F,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.149.0",
+  "version": "0.151.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {
@@ -36,6 +36,10 @@
     "./assistant-stream": {
       "types": "./dist/assistant-stream.d.ts",
       "default": "./dist/assistant-stream.js"
+    },
+    "./trace-sink": {
+      "types": "./dist/trace-sink.d.ts",
+      "default": "./dist/trace-sink.js"
     }
   },
   "files": [
@@ -44,7 +48,7 @@
   "devDependencies": {
     "@types/node": "^22.20.5",
     "typescript": "^7.0.0",
-    "vitest": "^5.0.3",
+    "vitest": "^5.0.5",
     "zod": "^4.4.3"
   },
   "publishConfig": {