@open-mercato/shared 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7000.1.0ae682bad1

package/dist/lib/telemetry/runtime.js

@@ -26,10 +26,23 @@ function getTelemetryRuntime() {
 function resetTelemetryRuntime() {
   store().active = void 0;
 }
+const NOOP_SPAN = { setAttributes() {
+} };
+function withTelemetrySpan(name, fn, options) {
+  const runtime = getTelemetryRuntime();
+  if (!runtime?.withSpan) return fn(NOOP_SPAN);
+  return runtime.withSpan(name, fn, options);
+}
+function captureTelemetryTrace() {
+  const carrier = getTelemetryRuntime()?.captureTraceContext();
+  return carrier && Object.keys(carrier).length > 0 ? carrier : void 0;
+}
 export {
+  captureTelemetryTrace,
   getTelemetryRuntime,
   isTelemetryBackendEnabled,
   registerTelemetryRuntime,
-  resetTelemetryRuntime
+  resetTelemetryRuntime,
+  withTelemetrySpan
 };
 //# sourceMappingURL=runtime.js.map

package/dist/lib/telemetry/runtime.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/telemetry/runtime.ts"],
-  "sourcesContent": ["export type TelemetryTraceCarrier = Record<string, string>\n\nexport type TelemetryRuntime = {\n  /**\n   * True only when the active SDK may safely use the process-global W3C\n   * propagator for cross-boundary extraction.\n   */\n  canUseGlobalTracePropagation(): boolean\n  captureTraceContext(): TelemetryTraceCarrier\n  continueTrace<T>(\n    carrier: TelemetryTraceCarrier | undefined,\n    name: string,\n    fn: () => T,\n    options?: { kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer' },\n  ): T\n  recordHttpDuration(method: string, route: string, status: number, startedAt: number): void\n  reportError(\n    error: unknown,\n    context?: {\n      module?: string\n      attributes?: Record<string, string | number | boolean | undefined>\n    },\n  ): void\n  shutdown(): Promise<void>\n}\n\nconst GLOBAL_KEY = Symbol.for('@open-mercato/shared.telemetryRuntime')\nconst ENABLED_BACKENDS = new Set(['console', 'signoz', 'newrelic', 'otlp'])\n\ntype TelemetryRuntimeStore = {\n  active?: TelemetryRuntime\n}\n\nfunction store(): TelemetryRuntimeStore {\n  const globalStore = globalThis as unknown as Record<symbol, TelemetryRuntimeStore | undefined>\n  let current = globalStore[GLOBAL_KEY]\n  if (!current) {\n    current = {}\n    globalStore[GLOBAL_KEY] = current\n  }\n  return current\n}\n\n/**\n * This check is intentionally owned by shared code so hosts can decide whether\n * to dynamically import the telemetry package without evaluating that package.\n */\nexport function isTelemetryBackendEnabled(raw?: string): boolean {\n  const value = raw ?? (\n    typeof process === 'undefined'\n      ? undefined\n      : process.env.TELEMETRY_BACKEND\n  )\n  return ENABLED_BACKENDS.has((value ?? '').trim().toLowerCase())\n}\n\nexport function registerTelemetryRuntime(runtime: TelemetryRuntime): () => void {\n  store().active = runtime\n  return () => {\n    const current = store()\n    if (current.active === runtime) current.active = undefined\n  }\n}\n\nexport function getTelemetryRuntime(): TelemetryRuntime | undefined {\n  return store().active\n}\n\n/** Test-only: clear the process-wide telemetry bridge. */\nexport function resetTelemetryRuntime(): void {\n  store().active = undefined\n}\n"],
-  "mappings": "AA0BA,MAAM,aAAa,uBAAO,IAAI,uCAAuC;AACrE,MAAM,mBAAmB,oBAAI,IAAI,CAAC,WAAW,UAAU,YAAY,MAAM,CAAC;AAM1E,SAAS,QAA+B;AACtC,QAAM,cAAc;AACpB,MAAI,UAAU,YAAY,UAAU;AACpC,MAAI,CAAC,SAAS;AACZ,cAAU,CAAC;AACX,gBAAY,UAAU,IAAI;AAAA,EAC5B;AACA,SAAO;AACT;AAMO,SAAS,0BAA0B,KAAuB;AAC/D,QAAM,QAAQ,QACZ,OAAO,YAAY,cACf,SACA,QAAQ,IAAI;AAElB,SAAO,iBAAiB,KAAK,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AAChE;AAEO,SAAS,yBAAyB,SAAuC;AAC9E,QAAM,EAAE,SAAS;AACjB,SAAO,MAAM;AACX,UAAM,UAAU,MAAM;AACtB,QAAI,QAAQ,WAAW,QAAS,SAAQ,SAAS;AAAA,EACnD;AACF;AAEO,SAAS,sBAAoD;AAClE,SAAO,MAAM,EAAE;AACjB;AAGO,SAAS,wBAA8B;AAC5C,QAAM,EAAE,SAAS;AACnB;",
+  "sourcesContent": ["export type TelemetryTraceCarrier = Record<string, string>\n\nexport type TelemetrySpanAttributes = Record<string, string | number | boolean | undefined>\n\nexport type TelemetrySpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'\n\n/** The subset of the telemetry package's `Span` that bridge consumers need. */\nexport type TelemetrySpan = {\n  setAttributes(attributes: TelemetrySpanAttributes): void\n  /**\n   * Rename an in-flight span whose identity is only known once it has run.\n   * Optional so a bootstrap predating it still satisfies the contract \u2014 call it\n   * as `span.updateName?.(\u2026)`.\n   */\n  updateName?(name: string): void\n}\n\nexport type TelemetrySpanOptions = {\n  kind?: TelemetrySpanKind\n  attributes?: TelemetrySpanAttributes\n  /** Start a new trace so the sampler decides for this span alone. */\n  root?: boolean\n  /** Causal links to other traces, as W3C carriers. */\n  links?: TelemetryTraceCarrier[]\n}\n\nexport type TelemetryRuntime = {\n  /**\n   * True only when the active SDK may safely use the process-global W3C\n   * propagator for cross-boundary extraction.\n   */\n  canUseGlobalTracePropagation(): boolean\n  captureTraceContext(): TelemetryTraceCarrier\n  continueTrace<T>(\n    carrier: TelemetryTraceCarrier | undefined,\n    name: string,\n    fn: () => T,\n    options?: { kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer' },\n  ): T\n  /**\n   * Optional so an older bootstrap that predates span support still satisfies\n   * the contract; consumers go through `withTelemetrySpan` and degrade to\n   * running `fn` untraced.\n   */\n  withSpan?<T>(name: string, fn: (span: TelemetrySpan) => T, options?: TelemetrySpanOptions): T\n  recordHttpDuration(method: string, route: string, status: number, startedAt: number): void\n  reportError(\n    error: unknown,\n    context?: {\n      module?: string\n      attributes?: Record<string, string | number | boolean | undefined>\n    },\n  ): void\n  shutdown(): Promise<void>\n}\n\nconst GLOBAL_KEY = Symbol.for('@open-mercato/shared.telemetryRuntime')\nconst ENABLED_BACKENDS = new Set(['console', 'signoz', 'newrelic', 'otlp'])\n\ntype TelemetryRuntimeStore = {\n  active?: TelemetryRuntime\n}\n\nfunction store(): TelemetryRuntimeStore {\n  const globalStore = globalThis as unknown as Record<symbol, TelemetryRuntimeStore | undefined>\n  let current = globalStore[GLOBAL_KEY]\n  if (!current) {\n    current = {}\n    globalStore[GLOBAL_KEY] = current\n  }\n  return current\n}\n\n/**\n * This check is intentionally owned by shared code so hosts can decide whether\n * to dynamically import the telemetry package without evaluating that package.\n */\nexport function isTelemetryBackendEnabled(raw?: string): boolean {\n  const value = raw ?? (\n    typeof process === 'undefined'\n      ? undefined\n      : process.env.TELEMETRY_BACKEND\n  )\n  return ENABLED_BACKENDS.has((value ?? '').trim().toLowerCase())\n}\n\nexport function registerTelemetryRuntime(runtime: TelemetryRuntime): () => void {\n  store().active = runtime\n  return () => {\n    const current = store()\n    if (current.active === runtime) current.active = undefined\n  }\n}\n\nexport function getTelemetryRuntime(): TelemetryRuntime | undefined {\n  return store().active\n}\n\n/** Test-only: clear the process-wide telemetry bridge. */\nexport function resetTelemetryRuntime(): void {\n  store().active = undefined\n}\n\nconst NOOP_SPAN: TelemetrySpan = { setAttributes() {} }\n\n/**\n * Run `fn` inside a span, from a package that must not depend on\n * `@open-mercato/telemetry`. With telemetry off this is `fn` plus one global\n * lookup \u2014 no span object is allocated and the OTEL SDK is never reached.\n *\n * Pass `root: true` for the unit of work a long-lived job should be sampled and\n * rendered by (a batch, a page) so the job is not one trace under one sampling\n * decision, and `links` to keep the causal chain back to what triggered it.\n */\nexport function withTelemetrySpan<T>(\n  name: string,\n  fn: (span: TelemetrySpan) => T,\n  options?: TelemetrySpanOptions,\n): T {\n  const runtime = getTelemetryRuntime()\n  if (!runtime?.withSpan) return fn(NOOP_SPAN)\n  return runtime.withSpan(name, fn, options)\n}\n\n/**\n * The active trace as a carrier, for use as a `links` entry. `undefined` when\n * telemetry is off or nothing is active, which `withTelemetrySpan` treats as\n * \"no link\" rather than an invalid one.\n */\nexport function captureTelemetryTrace(): TelemetryTraceCarrier | undefined {\n  const carrier = getTelemetryRuntime()?.captureTraceContext()\n  return carrier && Object.keys(carrier).length > 0 ? carrier : undefined\n}\n"],
+  "mappings": "AAwDA,MAAM,aAAa,uBAAO,IAAI,uCAAuC;AACrE,MAAM,mBAAmB,oBAAI,IAAI,CAAC,WAAW,UAAU,YAAY,MAAM,CAAC;AAM1E,SAAS,QAA+B;AACtC,QAAM,cAAc;AACpB,MAAI,UAAU,YAAY,UAAU;AACpC,MAAI,CAAC,SAAS;AACZ,cAAU,CAAC;AACX,gBAAY,UAAU,IAAI;AAAA,EAC5B;AACA,SAAO;AACT;AAMO,SAAS,0BAA0B,KAAuB;AAC/D,QAAM,QAAQ,QACZ,OAAO,YAAY,cACf,SACA,QAAQ,IAAI;AAElB,SAAO,iBAAiB,KAAK,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AAChE;AAEO,SAAS,yBAAyB,SAAuC;AAC9E,QAAM,EAAE,SAAS;AACjB,SAAO,MAAM;AACX,UAAM,UAAU,MAAM;AACtB,QAAI,QAAQ,WAAW,QAAS,SAAQ,SAAS;AAAA,EACnD;AACF;AAEO,SAAS,sBAAoD;AAClE,SAAO,MAAM,EAAE;AACjB;AAGO,SAAS,wBAA8B;AAC5C,QAAM,EAAE,SAAS;AACnB;AAEA,MAAM,YAA2B,EAAE,gBAAgB;AAAC,EAAE;AAW/C,SAAS,kBACd,MACA,IACA,SACG;AACH,QAAM,UAAU,oBAAoB;AACpC,MAAI,CAAC,SAAS,SAAU,QAAO,GAAG,SAAS;AAC3C,SAAO,QAAQ,SAAS,MAAM,IAAI,OAAO;AAC3C;AAOO,SAAS,wBAA2D;AACzE,QAAM,UAAU,oBAAoB,GAAG,oBAAoB;AAC3D,SAAO,WAAW,OAAO,KAAK,OAAO,EAAE,SAAS,IAAI,UAAU;AAChE;",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.6998.1.d2bc46c56c";
+const APP_VERSION = "0.6.8-develop.7000.1.0ae682bad1";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6998.1.d2bc46c56c';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.7000.1.0ae682bad1';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.6998.1.d2bc46c56c",
+  "version": "0.6.8-develop.7000.1.0ae682bad1",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -105,7 +105,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.6998.1.d2bc46c56c",
+    "@open-mercato/cache": "0.6.8-develop.7000.1.0ae682bad1",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/telemetry/__tests__/runtime.test.ts

@@ -0,0 +1,211 @@
+import {
+  captureTelemetryTrace,
+  getTelemetryRuntime,
+  isTelemetryBackendEnabled,
+  registerTelemetryRuntime,
+  resetTelemetryRuntime,
+  withTelemetrySpan,
+  type TelemetryRuntime,
+  type TelemetrySpan,
+  type TelemetrySpanOptions,
+  type TelemetryTraceCarrier,
+} from '../runtime'
+
+type SpanCall = { name: string; options?: TelemetrySpanOptions }
+
+function createRuntime(overrides: Partial<TelemetryRuntime> = {}): TelemetryRuntime {
+  return {
+    canUseGlobalTracePropagation: () => true,
+    captureTraceContext: () => ({}),
+    continueTrace: (_carrier, _name, fn) => fn(),
+    recordHttpDuration: () => {},
+    reportError: () => {},
+    shutdown: async () => {},
+    ...overrides,
+  }
+}
+
+function createTracingRuntime(): { runtime: TelemetryRuntime; calls: SpanCall[]; span: TelemetrySpan } {
+  const calls: SpanCall[] = []
+  const span: TelemetrySpan = { setAttributes: jest.fn(), updateName: jest.fn() }
+  const runtime = createRuntime({
+    withSpan: (name, fn, options) => {
+      calls.push({ name, options })
+      return fn(span)
+    },
+  })
+  return { runtime, calls, span }
+}
+
+describe('isTelemetryBackendEnabled', () => {
+  const originalBackend = process.env.TELEMETRY_BACKEND
+
+  afterEach(() => {
+    if (originalBackend === undefined) delete process.env.TELEMETRY_BACKEND
+    else process.env.TELEMETRY_BACKEND = originalBackend
+  })
+
+  it('recognizes every supported backend', () => {
+    for (const backend of ['console', 'signoz', 'newrelic', 'otlp']) {
+      expect(isTelemetryBackendEnabled(backend)).toBe(true)
+    }
+  })
+
+  it('normalizes surrounding whitespace and casing', () => {
+    expect(isTelemetryBackendEnabled('  CoNsOle  ')).toBe(true)
+    expect(isTelemetryBackendEnabled('\tOTLP\n')).toBe(true)
+  })
+
+  it('rejects unknown, blank, and missing values', () => {
+    expect(isTelemetryBackendEnabled('off')).toBe(false)
+    expect(isTelemetryBackendEnabled('consoles')).toBe(false)
+    expect(isTelemetryBackendEnabled('')).toBe(false)
+    expect(isTelemetryBackendEnabled('   ')).toBe(false)
+
+    delete process.env.TELEMETRY_BACKEND
+    expect(isTelemetryBackendEnabled()).toBe(false)
+  })
+
+  it('falls back to TELEMETRY_BACKEND only when no value is passed', () => {
+    process.env.TELEMETRY_BACKEND = 'signoz'
+    expect(isTelemetryBackendEnabled()).toBe(true)
+    expect(isTelemetryBackendEnabled('off')).toBe(false)
+
+    process.env.TELEMETRY_BACKEND = 'off'
+    expect(isTelemetryBackendEnabled()).toBe(false)
+    expect(isTelemetryBackendEnabled('console')).toBe(true)
+  })
+})
+
+describe('telemetry runtime registry', () => {
+  afterEach(() => {
+    resetTelemetryRuntime()
+  })
+
+  it('exposes no runtime until one is registered', () => {
+    expect(getTelemetryRuntime()).toBeUndefined()
+  })
+
+  it('exposes the registered runtime across separate lookups', () => {
+    const runtime = createRuntime()
+    registerTelemetryRuntime(runtime)
+
+    expect(getTelemetryRuntime()).toBe(runtime)
+    expect(getTelemetryRuntime()).toBe(runtime)
+  })
+
+  it('clears the runtime when its own disposer runs', () => {
+    const dispose = registerTelemetryRuntime(createRuntime())
+    dispose()
+
+    expect(getTelemetryRuntime()).toBeUndefined()
+  })
+
+  it('leaves a newer runtime in place when a superseded disposer runs', () => {
+    const first = createRuntime()
+    const second = createRuntime()
+    const disposeFirst = registerTelemetryRuntime(first)
+    registerTelemetryRuntime(second)
+
+    disposeFirst()
+
+    expect(getTelemetryRuntime()).toBe(second)
+  })
+
+  it('clears the runtime on reset', () => {
+    registerTelemetryRuntime(createRuntime())
+    resetTelemetryRuntime()
+
+    expect(getTelemetryRuntime()).toBeUndefined()
+  })
+})
+
+describe('withTelemetrySpan', () => {
+  afterEach(() => {
+    resetTelemetryRuntime()
+  })
+
+  it('runs the callback untraced with a usable noop span when telemetry is off', () => {
+    const seen: TelemetrySpan[] = []
+    const result = withTelemetrySpan('job.batch', (span) => {
+      seen.push(span)
+      span.setAttributes({ 'om.tenant_id': 'tenant-1', count: 2, ok: true })
+      span.updateName?.('job.batch.renamed')
+      return 'done'
+    })
+
+    expect(result).toBe('done')
+    expect(seen).toHaveLength(1)
+  })
+
+  it('runs the callback untraced when the registered runtime predates span support', () => {
+    registerTelemetryRuntime(createRuntime())
+
+    const result = withTelemetrySpan('job.batch', (span) => {
+      span.setAttributes({ ok: true })
+      return 41 + 1
+    })
+
+    expect(result).toBe(42)
+  })
+
+  it('delegates to the runtime and forwards the name, options, and span', () => {
+    const { runtime, calls, span } = createTracingRuntime()
+    registerTelemetryRuntime(runtime)
+
+    const options: TelemetrySpanOptions = {
+      kind: 'consumer',
+      root: true,
+      links: [{ traceparent: '00-aaaa-bbbb-01' }],
+      attributes: { 'data_sync.batch_index': 3 },
+    }
+
+    const result = withTelemetrySpan(
+      'data_sync.import.batch',
+      (received) => {
+        expect(received).toBe(span)
+        received.setAttributes({ 'data_sync.records': 10 })
+        return 'traced'
+      },
+      options,
+    )
+
+    expect(result).toBe('traced')
+    expect(calls).toEqual([{ name: 'data_sync.import.batch', options }])
+    expect(span.setAttributes).toHaveBeenCalledWith({ 'data_sync.records': 10 })
+  })
+
+  it('propagates a callback failure from the traced path', () => {
+    const { runtime } = createTracingRuntime()
+    registerTelemetryRuntime(runtime)
+
+    expect(() =>
+      withTelemetrySpan('data_sync.import.batch', () => {
+        throw new Error('[internal] batch failed')
+      }),
+    ).toThrow('[internal] batch failed')
+  })
+})
+
+describe('captureTelemetryTrace', () => {
+  afterEach(() => {
+    resetTelemetryRuntime()
+  })
+
+  it('returns undefined when telemetry is off', () => {
+    expect(captureTelemetryTrace()).toBeUndefined()
+  })
+
+  it('returns undefined when the active runtime captures an empty carrier', () => {
+    registerTelemetryRuntime(createRuntime({ captureTraceContext: () => ({}) }))
+
+    expect(captureTelemetryTrace()).toBeUndefined()
+  })
+
+  it('returns the captured carrier when a trace is active', () => {
+    const carrier: TelemetryTraceCarrier = { traceparent: '00-aaaa-bbbb-01' }
+    registerTelemetryRuntime(createRuntime({ captureTraceContext: () => carrier }))
+
+    expect(captureTelemetryTrace()).toEqual(carrier)
+  })
+})

package/src/lib/telemetry/runtime.ts

@@ -1,5 +1,29 @@
 export type TelemetryTraceCarrier = Record<string, string>
 
+export type TelemetrySpanAttributes = Record<string, string | number | boolean | undefined>
+
+export type TelemetrySpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'
+
+/** The subset of the telemetry package's `Span` that bridge consumers need. */
+export type TelemetrySpan = {
+  setAttributes(attributes: TelemetrySpanAttributes): void
+  /**
+   * Rename an in-flight span whose identity is only known once it has run.
+   * Optional so a bootstrap predating it still satisfies the contract — call it
+   * as `span.updateName?.(…)`.
+   */
+  updateName?(name: string): void
+}
+
+export type TelemetrySpanOptions = {
+  kind?: TelemetrySpanKind
+  attributes?: TelemetrySpanAttributes
+  /** Start a new trace so the sampler decides for this span alone. */
+  root?: boolean
+  /** Causal links to other traces, as W3C carriers. */
+  links?: TelemetryTraceCarrier[]
+}
+
 export type TelemetryRuntime = {
   /**
    * True only when the active SDK may safely use the process-global W3C
@@ -13,6 +37,12 @@ export type TelemetryRuntime = {
     fn: () => T,
     options?: { kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer' },
   ): T
+  /**
+   * Optional so an older bootstrap that predates span support still satisfies
+   * the contract; consumers go through `withTelemetrySpan` and degrade to
+   * running `fn` untraced.
+   */
+  withSpan?<T>(name: string, fn: (span: TelemetrySpan) => T, options?: TelemetrySpanOptions): T
   recordHttpDuration(method: string, route: string, status: number, startedAt: number): void
   reportError(
     error: unknown,
@@ -70,3 +100,34 @@ export function getTelemetryRuntime(): TelemetryRuntime | undefined {
 export function resetTelemetryRuntime(): void {
   store().active = undefined
 }
+
+const NOOP_SPAN: TelemetrySpan = { setAttributes() {} }
+
+/**
+ * Run `fn` inside a span, from a package that must not depend on
+ * `@open-mercato/telemetry`. With telemetry off this is `fn` plus one global
+ * lookup — no span object is allocated and the OTEL SDK is never reached.
+ *
+ * Pass `root: true` for the unit of work a long-lived job should be sampled and
+ * rendered by (a batch, a page) so the job is not one trace under one sampling
+ * decision, and `links` to keep the causal chain back to what triggered it.
+ */
+export function withTelemetrySpan<T>(
+  name: string,
+  fn: (span: TelemetrySpan) => T,
+  options?: TelemetrySpanOptions,
+): T {
+  const runtime = getTelemetryRuntime()
+  if (!runtime?.withSpan) return fn(NOOP_SPAN)
+  return runtime.withSpan(name, fn, options)
+}
+
+/**
+ * The active trace as a carrier, for use as a `links` entry. `undefined` when
+ * telemetry is off or nothing is active, which `withTelemetrySpan` treats as
+ * "no link" rather than an invalid one.
+ */
+export function captureTelemetryTrace(): TelemetryTraceCarrier | undefined {
+  const carrier = getTelemetryRuntime()?.captureTraceContext()
+  return carrier && Object.keys(carrier).length > 0 ? carrier : undefined
+}

package/src/modules/events/types.ts

@@ -62,6 +62,10 @@ export interface EventPayload {
 export interface EmitOptions {
   /** If true, the event will be persisted to a queue for async processing */
   persistent?: boolean
+  /** Trusted tenant scope forwarded to subscribers separately from the payload */
+  tenantId?: string | null
+  /** Trusted organization scope forwarded to subscribers separately from the payload */
+  organizationId?: string | null
 }
 
 // =============================================================================