@superblocksteam/telemetry 2.0.93 → 2.0.94-next.0

package/README.md

@@ -6,33 +6,38 @@ Canonical telemetry bootstrap package for all Superblocks services. This package
 
 This is the **ONLY approved way** to initialize OpenTelemetry in Superblocks services. Direct usage of `NodeSDK` or `WebTracerProvider` outside this package is prohibited.
 
+- **Logging**: Policy-aware log export (severity filtering, sanitization). See [docs/LOGGING.md](docs/LOGGING.md) for what to log at each level and forbidden fields.
+
 ## Tiered Telemetry Model
 
-| Tier | Description | Egress |
-|------|-------------|--------|
-| **Tier 1** | Full fidelity debugging (code, prompts, stack traces) | Local only (cloud-prem) |
-| **Tier 2** | Sanitized operational telemetry (latency, errors, token usage) | Exported by default |
-| **Tier 3** | AI experience telemetry (prompts, responses, quality signals) | Exported by default |
+| Tier       | Description                                                    | Egress                  |
+| ---------- | -------------------------------------------------------------- | ----------------------- |
+| **Tier 1** | Full fidelity debugging (code, prompts, stack traces)          | Local only (cloud-prem) |
+| **Tier 2** | Sanitized operational telemetry (latency, errors, token usage) | Exported by default     |
+| **Tier 3** | AI experience telemetry (prompts, responses, quality signals)  | Exported by default     |
 
 ## Usage
 
 ### Node.js Services
 
 ```typescript
-import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
-import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+import { initNodeTelemetry } from "@superblocksteam/telemetry/node";
+import { getDefaultPolicy, DeploymentType } from "@superblocksteam/shared";
 
 const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
 
-const telemetry = initNodeTelemetry({
-  serviceName: 'my-service',
-  serviceVersion: '1.0.0',
-  environment: process.env.NODE_ENV ?? 'development',
-  otlpUrl: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-}, policy);
+const telemetry = initNodeTelemetry(
+  {
+    serviceName: "my-service",
+    serviceVersion: "1.0.0",
+    environment: process.env.NODE_ENV ?? "development",
+    otlpUrl: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+  },
+  policy,
+);
 
 // Graceful shutdown
-process.on('SIGTERM', async () => {
+process.on("SIGTERM", async () => {
   await telemetry.shutdown();
 });
 ```
@@ -40,42 +45,45 @@ process.on('SIGTERM', async () => {
 ### Browser
 
 ```typescript
-import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
-import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+import { initBrowserTelemetry } from "@superblocksteam/telemetry/browser";
+import { getDefaultPolicy, DeploymentType } from "@superblocksteam/shared";
 
 const policy = getDefaultPolicy(DeploymentType.CLOUD);
 
-initBrowserTelemetry({
-  serviceName: 'superblocks-ui',
-  serviceVersion: '1.0.0',
-  environment: 'production',
-  otlpUrl: 'https://app.superblocks.com/api/v1/traces',
-}, policy);
+initBrowserTelemetry(
+  {
+    serviceName: "superblocks-ui",
+    serviceVersion: "1.0.0",
+    environment: "production",
+    otlpUrl: "https://app.superblocks.com/api/v1/traces",
+  },
+  policy,
+);
 ```
 
 ### Testing
 
 ```typescript
-import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+import { initTestTelemetry } from "@superblocksteam/telemetry/testing";
 
-describe('MyService', () => {
+describe("MyService", () => {
   const { spanExporter, reset } = initTestTelemetry();
 
   beforeEach(() => reset());
 
-  it('creates expected spans', async () => {
+  it("creates expected spans", async () => {
     await myService.doSomething();
 
     const spans = spanExporter.getSpans();
     expect(spans).toHaveLength(1);
-    expect(spans[0].name).toBe('doSomething');
+    expect(spans[0].name).toBe("doSomething");
   });
 
-  it('does not leak Tier 1 data', async () => {
+  it("does not leak Tier 1 data", async () => {
     await myService.processWithSensitiveData();
 
-    spanExporter.assertNoAttribute('prompt', /.*/);
-    spanExporter.assertNoAttribute('code', /.*/);
+    spanExporter.assertNoAttribute("prompt", /.*/);
+    spanExporter.assertNoAttribute("code", /.*/);
   });
 });
 ```
@@ -85,30 +93,34 @@ describe('MyService', () => {
 Use tier policy hints to inform the Collector how to route specific spans. This is useful when the SDK knows something the Collector can't infer from attributes alone.
 
 ```typescript
-import { trace } from '@opentelemetry/api';
-import { markSensitive, markForAIAnalysis, markDebugOnly } from '@superblocksteam/telemetry';
+import { trace } from "@opentelemetry/api";
+import {
+  markSensitive,
+  markForAIAnalysis,
+  markDebugOnly,
+} from "@superblocksteam/telemetry";
 
-const tracer = trace.getTracer('my-service');
+const tracer = trace.getTracer("my-service");
 
 // Span containing secrets — Tier 1 only, never exported
-tracer.startActiveSpan('decrypt_customer_secret', (span) => {
+tracer.startActiveSpan("decrypt_customer_secret", (span) => {
   markSensitive(span);
   // ... decrypt operation
   span.end();
 });
 
 // GenAI span for quality analysis — include in Tier 3
-tracer.startActiveSpan('gen_ai.chat', (span) => {
+tracer.startActiveSpan("gen_ai.chat", (span) => {
   markForAIAnalysis(span);
-  span.setAttribute('gen_ai.system', 'anthropic');
+  span.setAttribute("gen_ai.system", "anthropic");
   // ... LLM call
   span.end();
 });
 
 // High-cardinality debug span — skip export (cost control)
-tracer.startActiveSpan('debug.cache_lookup', (span) => {
+tracer.startActiveSpan("debug.cache_lookup", (span) => {
   markDebugOnly(span);
-  span.setAttribute('cache.key', cacheKey);
+  span.setAttribute("cache.key", cacheKey);
   // ... lookup
   span.end();
 });
@@ -116,16 +128,19 @@ tracer.startActiveSpan('debug.cache_lookup', (span) => {
 
 ### Available Hints
 
-| Helper | Hint Value | Effect |
-|--------|------------|--------|
-| `markSensitive(span)` | `tier1_only` | Tier 1 only, skip Tier 2/3 |
+| Helper                    | Hint Value      | Effect                           |
+| ------------------------- | --------------- | -------------------------------- |
+| `markSensitive(span)`     | `tier1_only`    | Tier 1 only, skip Tier 2/3       |
 | `markForAIAnalysis(span)` | `include_tier3` | Include in Tier 3 (AI analytics) |
-| `markDebugOnly(span)` | `skip_export` | Tier 1 only, skip all export |
+| `markDebugOnly(span)`     | `skip_export`   | Tier 1 only, skip all export     |
 
 You can also set hints directly:
 
 ```typescript
-import { TIER_HINT_ATTRIBUTE, TierPolicyHint } from '@superblocksteam/telemetry';
+import {
+  TIER_HINT_ATTRIBUTE,
+  TierPolicyHint,
+} from "@superblocksteam/telemetry";
 
 span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
 ```
@@ -143,7 +158,7 @@ span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
 ```
 @superblocksteam/telemetry
 ├── /node          # Node.js bootstrap (initNodeTelemetry)
-├── /browser       # Browser bootstrap (initBrowserTelemetry)  
+├── /browser       # Browser bootstrap (initBrowserTelemetry)
 ├── /testing       # Test utilities (in-memory exporters)
 └── /common        # Shared utilities (resource, router, sanitizer)
 ```
@@ -152,4 +167,4 @@ span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
 
 - [O11y Refactor Project](../../engineering/projects/o11y-refactor/README.md)
 - [Telemetry Policy Schema](../../engineering/projects/o11y-refactor/epics/epic-a1-telemetry-policy.md)
-- [Tier 2 Traces Contract](https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/contracts/tier2-traces.v0.3.0.json)
+- [Tier 2 Traces Contract](https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/contracts/tier2-traces.v0.2.0.json)

package/dist/browser/index.d.ts

@@ -3,6 +3,6 @@
  *
  * This is the ONLY approved way to initialize telemetry in browser contexts.
  */
-export { initBrowserTelemetry, getBrowserTelemetryInstance, isBrowserTelemetryInitialized, resetBrowserTelemetry, getEnvironmentFromHostname, type BrowserTelemetryInstance, } from './init.js';
-export { getDefaultPolicy, DeploymentType } from '../types/policy.js';
+export { initBrowserTelemetry, getBrowserTelemetryInstance, isBrowserTelemetryInitialized, resetBrowserTelemetry, getEnvironmentFromHostname, type BrowserTelemetryInstance, } from "./init.js";
+export { getDefaultPolicy, DeploymentType } from "../types/policy.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/resilient-exporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resilient-exporter.d.ts","sourceRoot":"","sources":["../../src/browser/resilient-exporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAoB,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,eAAe,GAAG,SAAS,KAAK,IAAI,CAAC;CACtF;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGb;IAEV,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,8BAA8B;IAOlD;;OAEG;IACH,MAAM,CACJ,KAAK,EAAE,YAAY,EAAE,EACrB,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAC7C,IAAI;IAiDD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAKzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}
+{"version":3,"file":"resilient-exporter.d.ts","sourceRoot":"","sources":["../../src/browser/resilient-exporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAoB,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,CACP,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,GAAG,eAAe,GAAG,SAAS,KAC/C,IAAI,CAAC;CACX;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGb;IAEV,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,8BAA8B;IAOlD;;OAEG;IACH,MAAM,CACJ,KAAK,EAAE,YAAY,EAAE,EACrB,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAC7C,IAAI;IAiDD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAKzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/browser/resilient-exporter.js.map

@@ -1 +1 @@
-{"version":3,"file":"resilient-exporter.js","sourceRoot":"","sources":["../../src/browser/resilient-exporter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resilient-exporter.js","sourceRoot":"","sources":["../../src/browser/resilient-exporter.ts"],"names":[],"mappings":"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"}

package/dist/common/contracts/tier2-traces.d.ts

@@ -1,75 +1,87 @@
 /**
- * Tier 2 Traces Contract
+ * Tier 2 Traces Contract (v0.2.0)
  *
- * This file defines the Tier 2 telemetry contract:
- * - Forbidden attributes (removed by Collector)
- * - Hashed attributes (pseudonymized by Collector)
- * - Dropped attributes (removed by Collector)
- * - Forbidden value patterns (for lint-time detection)
+ * Single source of truth for Tier 2 sanitized trace telemetry.
+ * Mirrors: engineering/projects/o11y-refactor/contracts/tier2-traces.v0.2.0.json
  *
- * ENFORCEMENT: The OTEL Collector handles runtime enforcement.
- * These definitions are used for:
- * - ESLint rules (static analysis at CI time)
- * - Development warnings (guardrails.ts)
+ * Used by:
+ * - trace-sanitizer (SDK: which spans/attributes to export)
+ * - lint/forbidden-attributes (ESLint)
+ * - guardrails (dev-time warnings)
  * - Collector config generation
  *
- * See: obs/otel-collector/config-tiered.yaml
- * Source of truth: engineering/projects/o11y-refactor/contracts/tier2-traces.v0.3.0.json
+ * "request handler *" is a local extension for Express instrumentation (not in JSON).
  */
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+export interface AttributeDefinition {
+    name: string;
+    allowedValues?: string[];
+    maxCardinality?: number;
+    type?: "string" | "number" | "boolean";
+}
+export type AllowedAttribute = string | AttributeDefinition;
+export interface SpanDefinition {
+    name: string;
+    description?: string;
+    allowedAttributes: AllowedAttribute[];
+    alwaysSample?: boolean;
+}
+export declare function getAttributeName(attr: AllowedAttribute): string;
 /**
- * Attributes that are FORBIDDEN in Tier 2 telemetry.
- * These contain sensitive data that should never leave the customer's environment.
- * The Collector strips these entirely (not hashed, not present in Tier 2).
+ * Span patterns from tier2-traces.v0.2.0.json.
+ * Suffix wildcard only: "HTTP POST *" matches "HTTP POST /api/..." or "POST /api/...".
  */
-export declare const TIER2_FORBIDDEN_ATTRIBUTES: Set<string>;
+export declare const TIER_2_TRACE_CONTRACT: SpanDefinition[];
 /**
- * Attributes that should be HASHED (pseudonymized) in Tier 2 telemetry.
- * The Collector replaces these with SHA256 hashes for privacy.
- * Hashes enable aggregate analysis without exposing plaintext identifiers.
- *
- * Mapping:
- *   user-email, user.email, etc. → user.hash
- *   organization-id, organization_id → organization.hash
- *   application-id, application_id → application.hash
- *   session.id → session.hash
- *   enduser.id → enduser.pseudo.id
+ * Cloud trace contract: match-all span name ("*") so no spans are dropped by name.
+ * Attribute allowlist is not used when attributeAllowlistPassthrough is true.
  */
-export declare const TIER2_HASHED_ATTRIBUTES: Set<string>;
+export declare const CLOUD_TRACE_CONTRACT: SpanDefinition[];
 /**
- * Attributes that should be DROPPED entirely in Tier 2.
- * These are correlation IDs that don't provide operational value.
+ * Returns the trace contract (span definitions) for the given deployment type.
+ * Cloud: match-all so no traces are dropped by span name.
+ * Cloud-prem: Tier 2 contract (named spans only).
  */
+export declare function getTraceContract(deploymentType: DeploymentTypeEnum): SpanDefinition[];
+/** Forbidden in Tier 2 (forbiddenAttributes in contract). Collector strips these entirely. */
+export declare const FORBIDDEN_TIER_2_SPAN_ATTRIBUTES: string[];
+/** Hashed (keyed HMAC) for Tier 2 (hashedAttributes in contract). */
+export declare const HASHED_TIER_2_SPAN_ATTRIBUTES: string[];
+/** Dropped — high cardinality, no hash value (droppedAttributes in contract). */
+export declare const DROPPED_HIGH_CARDINALITY_ATTRIBUTES: string[];
+export declare const TIER2_FORBIDDEN_ATTRIBUTES: Set<string>;
+export declare const TIER2_HASHED_ATTRIBUTES: Set<string>;
 export declare const TIER2_DROPPED_ATTRIBUTES: Set<string>;
 /**
- * Spans that should ALWAYS be sampled (never dropped by rate limiting).
+ * Attribute sets and contract options used by TraceSanitizer.
+ * Allows different rules per deployment type (e.g. cloud vs cloud-prem).
  */
-export declare const ALWAYS_SAMPLE_SPANS: Set<string>;
+export interface TraceSanitizerAttributeSets {
+    forbiddenAttributes: Set<string>;
+    droppedAttributes: Set<string>;
+    hashedAttributes: Set<string>;
+    /** Span definitions for name matching; cloud uses match-all ("*"). */
+    spanDefinitions: SpanDefinition[];
+    /** When true, span attributes are not filtered by allowedAttributes (pass-through). */
+    attributeAllowlistPassthrough: boolean;
+}
 /**
- * Patterns that indicate forbidden content in attribute values.
- * Used for secondary filtering when attribute names aren't explicit.
- *
- * IMPORTANT: Patterns should NOT use ^ and $ anchors so they match
- * secrets embedded anywhere in a string (e.g., in query params, headers).
+ * Returns the Tier 2 trace attribute sets and contract options for the given deployment type.
+ * Cloud: relaxed policy (no attributes dropped/hashed), match-all span names, pass-through attributes.
+ * Cloud-prem: full Tier 2 contract (forbidden/dropped/hashed), named spans only, pass-through attributes.
  */
-export declare const FORBIDDEN_VALUE_PATTERNS: RegExp[];
+export declare function getTraceSanitizerAttributeSets(deploymentType: DeploymentTypeEnum): TraceSanitizerAttributeSets;
+/** Spans that should ALWAYS be sampled (samplingPolicy.alwaysSampleSpans in contract). */
+export declare const ALWAYS_SAMPLE_SPANS: Set<string>;
 /**
- * Check if an attribute name is forbidden in Tier 2.
+ * Patterns that indicate forbidden content in attribute values (e.g. secrets in strings).
+ * No ^/$ anchors so they match secrets embedded anywhere.
+ * It's not used by TraceSanitizer, only in guardrails.
  */
+export declare const FORBIDDEN_VALUE_PATTERNS: RegExp[];
 export declare function isForbiddenAttribute(name: string): boolean;
-/**
- * Check if an attribute should be hashed in Tier 2.
- */
 export declare function isHashedAttribute(name: string): boolean;
-/**
- * Check if an attribute should be dropped in Tier 2.
- */
 export declare function isDroppedAttribute(name: string): boolean;
-/**
- * Check if a value contains forbidden patterns (like tokens, keys).
- */
 export declare function containsForbiddenPattern(value: unknown): boolean;
-/**
- * Check if a span should always be sampled.
- */
 export declare function shouldAlwaysSample(spanName: string): boolean;
 //# sourceMappingURL=tier2-traces.d.ts.map

package/dist/common/contracts/tier2-traces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tier2-traces.d.ts","sourceRoot":"","sources":["../../../src/common/contracts/tier2-traces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,aAsDrC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,aAmBlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB,aAQnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB,aAE9B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,UAuBpC,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE5D"}
+{"version":3,"file":"tier2-traces.d.ts","sourceRoot":"","sources":["../../../src/common/contracts/tier2-traces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAM7D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,EAkWjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,cAAc,EAEhD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,kBAAkB,GACjC,cAAc,EAAE,CAQlB;AAMD,8FAA8F;AAC9F,eAAO,MAAM,gCAAgC,EAAE,MAAM,EAmCpD,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAAO,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,MAAM,EAAqB,CAAC;AAM9E,eAAO,MAAM,0BAA0B,aAEtC,CAAC;AACF,eAAO,MAAM,uBAAuB,aAAyC,CAAC;AAC9E,eAAO,MAAM,wBAAwB,aAEpC,CAAC;AASF;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,sEAAsE;IACtE,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,uFAAuF;IACvF,6BAA6B,EAAE,OAAO,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,kBAAkB,GACjC,2BAA2B,CAsB7B;AAMD,0FAA0F;AAC1F,eAAO,MAAM,mBAAmB,aAA2B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,UAQpC,CAAC;AAMF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE5D"}