@contrail/cli 3.5.0-alpha.d435e43 → 3.5.0-alpha.dd20a19

package/README.md

@@ -17,7 +17,7 @@ $ npm install -g @contrail/cli
 $ contrail COMMAND
 running command...
 $ contrail (--version)
-@contrail/cli/3.5.0-alpha.d435e43 linux-x64 node-v24.14.1
+@contrail/cli/3.5.0-alpha.dd20a19 linux-x64 node-v24.14.1
 $ contrail --help [COMMAND]
 USAGE
   $ contrail COMMAND
@@ -51,6 +51,7 @@ To get instructions on how to set up autocomplete for your shell, run `contrail
 * [`contrail config list`](#contrail-config-list)
 * [`contrail config set`](#contrail-config-set)
 * [`contrail config use [NAME]`](#contrail-config-use-name)
+* [`contrail event-workflows assess-impact IDENTIFIER`](#contrail-event-workflows-assess-impact-identifier)
 * [`contrail file upload FILELOCATION CONTENTTYPE`](#contrail-file-upload-filelocation-contenttype)
 * [`contrail groups export`](#contrail-groups-export)
 * [`contrail groups import GROUPSFILE`](#contrail-groups-import-groupsfile)
@@ -536,6 +537,37 @@ EXAMPLES
   $ contrail config use demo-org
 ```
 
+## `contrail event-workflows assess-impact IDENTIFIER`
+
+Sample Dash0 traces of an event-workflow action and report per-invocation downstream impact.
+
+```
+USAGE
+  $ contrail event-workflows assess-impact IDENTIFIER [-l error|warn|info|debug] [-e true|false] [-s <value>] [--lookback <value>]
+    [--dataset <value>] [-j]
+
+ARGUMENTS
+  IDENTIFIER  Action identifier (contrail.event_workflow.action.identifier).
+
+FLAGS
+  -e, --alwaysConfirmEnv=<option>  [default: true] The Environment variables
+                                   <options: true|false>
+  -j, --json                       JSON output (not yet implemented; flag reserved).
+  -l, --logLevel=<option>          The Log Level
+                                   <options: error|warn|info|debug>
+  -s, --samples=<value>            [default: 50] Number of distinct traces to sample (10-100).
+  --dataset=<value>                [default: prod] Dash0 dataset.
+  --lookback=<value>               [default: 2d] How far back to search. Format: 30m | 6h | 2d.
+
+DESCRIPTION
+  Sample Dash0 traces of an event-workflow action and report per-invocation downstream impact.
+
+EXAMPLES
+  $ contrail event-workflows assess-impact @gap-automations:bomCcCostUpdate
+
+  $ contrail event-workflows assess-impact @gap-automations:bomCcCostUpdate --samples 25 --lookback 6h
+```
+
 ## `contrail file upload FILELOCATION CONTENTTYPE`
 
 Uploads a file to the VibeIQ platform

package/dist/api/dash0/client.d.ts

@@ -0,0 +1,13 @@
+import { GetSpansRequest, GetSpansResponse } from './types';
+export interface Dash0ClientOptions {
+    token: string;
+    dataset: string;
+    apiUrl?: string;
+}
+export declare class Dash0Client {
+    private readonly http;
+    private readonly dataset;
+    constructor(opts: Dash0ClientOptions);
+    getSpans(req: GetSpansRequest): Promise<GetSpansResponse>;
+}
+export declare function dash0ClientFromEnv(dataset: string): Dash0Client;

package/dist/api/dash0/client.js

@@ -0,0 +1,53 @@
+"use strict";
+// Minimal Dash0 REST client.
+//
+// Contract verified by hand against api.us-west-2.aws.dash0.com on 2026-05-08:
+//   POST /api/spans
+//     headers: Authorization: Bearer ${DASH0_TOKEN}
+//              Content-Type: application/json
+//              Dash0-Dataset: <dataset>      (REQUIRED — body field is ignored)
+//     body:    { filter?: AttributeFilter[], timeRange: {from,to}, pagination?: {limit,cursor} }
+//              NOTE: the field is "filter" (singular). "filters" is silently ignored.
+//   Response uses OTLP/JSON: traceId/spanId are base64.
+//   Pagination via cursors.after → next call's pagination.cursor.
+//
+// Trace expansion uses the same endpoint: filter on `otel.trace.id` (hex).
+// There is no separate trace-details endpoint (the binary's /api/trace-details path 404s).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dash0ClientFromEnv = exports.Dash0Client = void 0;
+const tslib_1 = require("tslib");
+const axios_1 = tslib_1.__importDefault(require("axios"));
+const DEFAULT_API_URL = 'https://api.us-west-2.aws.dash0.com';
+class Dash0Client {
+    http;
+    dataset;
+    constructor(opts) {
+        this.dataset = opts.dataset;
+        this.http = axios_1.default.create({
+            baseURL: opts.apiUrl ?? DEFAULT_API_URL,
+            headers: {
+                Authorization: `Bearer ${opts.token}`,
+                'Content-Type': 'application/json',
+                'Dash0-Dataset': opts.dataset,
+            },
+            timeout: 30000,
+        });
+    }
+    async getSpans(req) {
+        const { data } = await this.http.post('/api/spans', req);
+        return data;
+    }
+}
+exports.Dash0Client = Dash0Client;
+function dash0ClientFromEnv(dataset) {
+    const token = process.env.DASH0_TOKEN;
+    if (!token) {
+        throw new Error('DASH0_TOKEN environment variable is required. Create one at https://app.dash0.com/settings/auth-tokens.');
+    }
+    return new Dash0Client({
+        token,
+        dataset,
+        apiUrl: process.env.DASH0_API_URL,
+    });
+}
+exports.dash0ClientFromEnv = dash0ClientFromEnv;

package/dist/api/dash0/spans.d.ts

@@ -0,0 +1,8 @@
+import { Dash0Client } from './client';
+import { AttributeFilter, FlatSpan, OtlpAttribute, OtlpResourceSpans, OtlpSpan, TimeReferenceRange } from './types';
+export declare function paginateSpans(client: Dash0Client, filter: AttributeFilter[], timeRange: TimeReferenceRange, limit?: number): AsyncGenerator<OtlpResourceSpans, void, void>;
+export declare function sampleTraceIdsForAction(client: Dash0Client, actionIdentifier: string, timeRange: TimeReferenceRange, maxTraces: number): Promise<string[]>;
+export declare function fetchTraceSpans(client: Dash0Client, traceIdHex: string, timeRange: TimeReferenceRange): Promise<FlatSpan[]>;
+export declare function toFlat(sp: OtlpSpan, resourceAttrs: Record<string, string | number | boolean>): FlatSpan;
+export declare function flattenAttrs(attrs: OtlpAttribute[]): Record<string, string | number | boolean>;
+export declare function b64ToHex(b64: string): string;

package/dist/api/dash0/spans.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.b64ToHex = exports.flattenAttrs = exports.toFlat = exports.fetchTraceSpans = exports.sampleTraceIdsForAction = exports.paginateSpans = void 0;
+const PAGE_LIMIT = 50;
+const MAX_PAGES_PER_QUERY = 200;
+async function* paginateSpans(client, filter, timeRange, limit = PAGE_LIMIT) {
+    let cursor;
+    for (let page = 0; page < MAX_PAGES_PER_QUERY; page++) {
+        const req = {
+            filter,
+            timeRange,
+            pagination: { limit, cursor },
+        };
+        const resp = await client.getSpans(req);
+        for (const r of resp.resourceSpans ?? [])
+            yield r;
+        cursor = resp.cursors?.after;
+        if (!cursor)
+            return;
+    }
+}
+exports.paginateSpans = paginateSpans;
+async function sampleTraceIdsForAction(client, actionIdentifier, timeRange, maxTraces) {
+    const seen = new Set();
+    for await (const rs of paginateSpans(client, [
+        {
+            key: 'contrail.event_workflow.action.identifier',
+            operator: 'is',
+            value: actionIdentifier,
+        },
+    ], timeRange)) {
+        for (const ss of rs.scopeSpans ?? []) {
+            for (const sp of ss.spans ?? []) {
+                seen.add(b64ToHex(sp.traceId));
+                if (seen.size >= maxTraces)
+                    return [...seen];
+            }
+        }
+    }
+    return [...seen];
+}
+exports.sampleTraceIdsForAction = sampleTraceIdsForAction;
+async function fetchTraceSpans(client, traceIdHex, timeRange) {
+    const out = [];
+    for await (const rs of paginateSpans(client, [{ key: 'otel.trace.id', operator: 'is', value: traceIdHex }], timeRange)) {
+        const resourceAttrs = flattenAttrs(rs.resource?.attributes ?? []);
+        for (const ss of rs.scopeSpans ?? []) {
+            for (const sp of ss.spans ?? [])
+                out.push(toFlat(sp, resourceAttrs));
+        }
+    }
+    return out;
+}
+exports.fetchTraceSpans = fetchTraceSpans;
+function toFlat(sp, resourceAttrs) {
+    const startNs = BigInt(sp.startTimeUnixNano);
+    const endNs = BigInt(sp.endTimeUnixNano);
+    return {
+        name: sp.name,
+        traceId: b64ToHex(sp.traceId),
+        spanId: b64ToHex(sp.spanId),
+        parentSpanId: sp.parentSpanId ? b64ToHex(sp.parentSpanId) : '',
+        kind: sp.kind,
+        startNs,
+        endNs,
+        durationNs: endNs - startNs,
+        attrs: flattenAttrs(sp.attributes ?? []),
+        resourceAttrs,
+    };
+}
+exports.toFlat = toFlat;
+function flattenAttrs(attrs) {
+    const out = {};
+    for (const a of attrs) {
+        const v = a.value ?? {};
+        if (v.stringValue !== undefined)
+            out[a.key] = v.stringValue;
+        else if (v.intValue !== undefined)
+            out[a.key] = Number(v.intValue);
+        else if (v.boolValue !== undefined)
+            out[a.key] = v.boolValue;
+        else if (v.doubleValue !== undefined)
+            out[a.key] = v.doubleValue;
+    }
+    return out;
+}
+exports.flattenAttrs = flattenAttrs;
+function b64ToHex(b64) {
+    return Buffer.from(b64, 'base64').toString('hex');
+}
+exports.b64ToHex = b64ToHex;

package/dist/api/dash0/types.d.ts

@@ -0,0 +1,84 @@
+export type AttributeFilterOperator = 'is' | 'is_not' | 'is_set' | 'is_not_set' | 'is_one_of' | 'is_not_one_of' | 'gt' | 'gte' | 'lt' | 'lte' | 'matches' | 'does_not_match' | 'contains' | 'does_not_contain' | 'starts_with' | 'does_not_start_with' | 'ends_with' | 'does_not_end_with';
+export interface AttributeFilter {
+    key: string;
+    operator: AttributeFilterOperator;
+    value?: string;
+    values?: string[];
+}
+export interface TimeReferenceRange {
+    from: string;
+    to: string;
+}
+export interface CursorPagination {
+    limit?: number;
+    cursor?: string;
+}
+export interface GetSpansRequest {
+    filter?: AttributeFilter[];
+    timeRange: TimeReferenceRange;
+    pagination?: CursorPagination;
+}
+export interface OtlpAttribute {
+    key: string;
+    value: {
+        stringValue?: string;
+        intValue?: string | number;
+        boolValue?: boolean;
+        doubleValue?: number;
+        arrayValue?: {
+            values: OtlpAttribute['value'][];
+        };
+    };
+}
+export interface OtlpSpan {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpAttribute[];
+    status: {
+        code: number;
+        message?: string;
+    };
+    events?: unknown[];
+    links?: unknown[];
+}
+export interface OtlpScopeSpans {
+    scope?: {
+        name?: string;
+        version?: string;
+    };
+    spans: OtlpSpan[];
+}
+export interface OtlpResourceSpans {
+    resource: {
+        attributes: OtlpAttribute[];
+    };
+    scopeSpans: OtlpScopeSpans[];
+}
+export interface NextCursors {
+    after?: string;
+    before?: string;
+}
+export interface GetSpansResponse {
+    resourceSpans: OtlpResourceSpans[];
+    cursors?: NextCursors;
+    executionTime?: string;
+}
+export interface FlatSpan {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+    kind: number;
+    startNs: bigint;
+    endNs: bigint;
+    durationNs: bigint;
+    attrs: Record<string, string | number | boolean>;
+    resourceAttrs: Record<string, string | number | boolean>;
+    depthFromAction?: number;
+    serverAncestorCount?: number;
+}

package/dist/api/dash0/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// OTLP/JSON span shape returned by Dash0 POST /api/spans.
+// Field types match https://github.com/dash0hq/dash0-api-client-go (generated.go).
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/event-workflows/assess-impact.d.ts

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../basecommand';
+export default class AssessImpact extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        identifier: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        samples: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        lookback: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        dataset: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        alwaysConfirmEnv: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        logLevel: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
+    skipValidateEnv: boolean;
+    skipConfirmEnv: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/event-workflows/assess-impact.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const basecommand_1 = require("../../basecommand");
+const client_1 = require("../../api/dash0/client");
+const spans_1 = require("../../api/dash0/spans");
+const subtree_1 = require("../../helpers/event-workflow-impact/subtree");
+const aggregate_1 = require("../../helpers/event-workflow-impact/aggregate");
+const render_1 = require("../../helpers/event-workflow-impact/render");
+const LOOKBACK_PATTERN = /^\d+(?:m|h|d)$/;
+class AssessImpact extends basecommand_1.BaseCommand {
+    static description = "Sample Dash0 traces of an event-workflow action and report per-invocation downstream impact.";
+    static examples = [
+        'contrail event-workflows assess-impact @gap-automations:bomCcCostUpdate',
+        'contrail event-workflows assess-impact @gap-automations:bomCcCostUpdate --samples 25 --lookback 6h',
+    ];
+    static args = {
+        identifier: core_1.Args.string({
+            description: 'Action identifier (contrail.event_workflow.action.identifier).',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...basecommand_1.BaseCommand.baseFlags,
+        samples: core_1.Flags.integer({
+            char: 's',
+            description: 'Number of distinct traces to sample (10-100).',
+            default: 50,
+            min: 10,
+            max: 100,
+        }),
+        lookback: core_1.Flags.string({
+            description: 'How far back to search. Format: 30m | 6h | 2d.',
+            default: '2d',
+        }),
+        dataset: core_1.Flags.string({
+            description: 'Dash0 dataset.',
+            default: 'prod',
+        }),
+        json: core_1.Flags.boolean({
+            char: 'j',
+            description: 'JSON output (not yet implemented; flag reserved).',
+            default: false,
+        }),
+    };
+    // No vibeiq auth or env confirmation — this hits Dash0, not the contrail API.
+    skipValidateEnv = true;
+    skipConfirmEnv = true;
+    async run() {
+        const { identifier } = this.args;
+        const { samples, lookback, dataset } = this.flags;
+        if (!LOOKBACK_PATTERN.test(lookback)) {
+            this.error(`--lookback must look like 30m, 6h, or 2d (got: ${lookback}).`);
+        }
+        const client = (0, client_1.dash0ClientFromEnv)(dataset);
+        const timeRange = { from: `now-${lookback}`, to: 'now' };
+        this.log(`Action:    ${identifier}`);
+        this.log(`Dataset:   ${dataset}`);
+        this.log(`Lookback:  ${lookback}`);
+        this.log(`Samples:   target ${samples}`);
+        this.log('');
+        this.log('Sampling trace IDs...');
+        const traceIds = await (0, spans_1.sampleTraceIdsForAction)(client, identifier, timeRange, samples);
+        if (traceIds.length === 0) {
+            this.warn(`No spans found for action.identifier="${identifier}" in the last ${lookback}. ` +
+                'Verify the identifier and dataset.');
+            return;
+        }
+        this.log(`Got ${traceIds.length} trace(s). Fetching subtrees...`);
+        const perTraceDescendants = [];
+        let dropped = 0;
+        let totalOrphans = 0;
+        let preciseRootCount = 0;
+        for (const traceId of traceIds) {
+            const spans = await (0, spans_1.fetchTraceSpans)(client, traceId, timeRange);
+            const result = (0, subtree_1.extractActionSubtree)(spans, identifier);
+            if (!result) {
+                dropped++;
+                continue;
+            }
+            perTraceDescendants.push(result.descendants);
+            totalOrphans += result.orphanCount;
+            if (result.preciseRoot)
+                preciseRootCount++;
+        }
+        if (perTraceDescendants.length === 0) {
+            this.warn('No traces yielded a usable action subtree.');
+            return;
+        }
+        const agg = (0, aggregate_1.aggregate)({ perTraceDescendants });
+        this.log('');
+        this.log((0, render_1.renderReport)(agg, {
+            identifier,
+            dataset,
+            lookback,
+            samplesRequested: samples,
+            samplesObtained: perTraceDescendants.length,
+            tracesDropped: dropped,
+            totalOrphanCount: totalOrphans,
+            preciseRootCount,
+        }));
+    }
+}
+exports.default = AssessImpact;

package/dist/helpers/event-workflow-impact/aggregate.d.ts

@@ -0,0 +1,23 @@
+import { FlatSpan } from '../../api/dash0/types';
+import { Category } from './classify';
+export interface BucketKey {
+    category: Category;
+    service: string;
+    operation: string;
+}
+export interface BucketStats {
+    key: BucketKey;
+    median: number;
+    p95: number;
+    max: number;
+    coverage: number;
+}
+export interface AggregateInput {
+    perTraceDescendants: FlatSpan[][];
+}
+export interface AggregateResult {
+    traceCount: number;
+    buckets: BucketStats[];
+}
+export declare function aggregate(input: AggregateInput): AggregateResult;
+export declare function percentile(values: number[], p: number): number;

package/dist/helpers/event-workflow-impact/aggregate.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.percentile = exports.aggregate = void 0;
+const classify_1 = require("./classify");
+const keyId = (k) => `${k.category}\x1f${k.service}\x1f${k.operation}`;
+function aggregate(input) {
+    const traceCount = input.perTraceDescendants.length;
+    // bucketKey -> per-trace count vector (length = traceCount)
+    const counts = new Map();
+    input.perTraceDescendants.forEach((spans, traceIdx) => {
+        for (const span of spans) {
+            const c = (0, classify_1.classifySpan)(span);
+            if (!c)
+                continue;
+            bumpBucket(counts, c, traceIdx, traceCount);
+        }
+    });
+    const buckets = [];
+    for (const { key, counts: vec } of counts.values()) {
+        buckets.push({
+            key,
+            median: percentile(vec, 0.5),
+            p95: percentile(vec, 0.95),
+            max: vec.reduce((a, b) => Math.max(a, b), 0),
+            coverage: vec.filter((n) => n > 0).length / Math.max(traceCount, 1),
+        });
+    }
+    return { traceCount, buckets };
+}
+exports.aggregate = aggregate;
+function bumpBucket(counts, c, traceIdx, traceCount) {
+    const k = { category: c.category, service: c.service, operation: c.operation };
+    const id = keyId(k);
+    let entry = counts.get(id);
+    if (!entry) {
+        entry = { key: k, counts: new Array(traceCount).fill(0) };
+        counts.set(id, entry);
+    }
+    entry.counts[traceIdx] += 1;
+}
+function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    // Nearest-rank, clamped.
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+    return sorted[idx];
+}
+exports.percentile = percentile;

package/dist/helpers/event-workflow-impact/aggregate.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/helpers/event-workflow-impact/aggregate.spec.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const aggregate_1 = require("./aggregate");
+function clientHttp(target, service = 'contrail-items') {
+    return {
+        name: 'GET',
+        traceId: 't',
+        spanId: Math.random().toString(36),
+        parentSpanId: '',
+        kind: 3,
+        startNs: 0n,
+        endNs: 0n,
+        durationNs: 0n,
+        attrs: { 'http.request.method': 'GET', 'http.target': target },
+        resourceAttrs: { 'service.name': service },
+        depthFromAction: 1,
+    };
+}
+function dynamoQuery() {
+    return {
+        name: 'DynamoDB.Query',
+        traceId: 't',
+        spanId: Math.random().toString(36),
+        parentSpanId: '',
+        kind: 4,
+        startNs: 0n,
+        endNs: 0n,
+        durationNs: 0n,
+        attrs: {},
+        resourceAttrs: {},
+    };
+}
+describe('percentile', () => {
+    it('handles empty arrays', () => {
+        expect((0, aggregate_1.percentile)([], 0.5)).toBe(0);
+    });
+    it('computes nearest-rank percentiles', () => {
+        expect((0, aggregate_1.percentile)([0, 0, 1, 1, 2, 2, 3, 3, 4, 4], 0.5)).toBe(2);
+        expect((0, aggregate_1.percentile)([0, 0, 1, 1, 2, 2, 3, 3, 4, 4], 0.95)).toBe(4);
+    });
+});
+describe('aggregate', () => {
+    it('counts occurrences per trace and computes median/p95/max/coverage', () => {
+        // 4 traces; varying fan-out for two HTTP buckets and one dynamo bucket.
+        const perTrace = [
+            // trace 1: 2 GET /items, 1 PUT /batch, 5 dynamo
+            [
+                clientHttp('/api/items'),
+                clientHttp('/api/items'),
+                { ...clientHttp('/api/items/batch'), name: 'PUT', attrs: { 'http.request.method': 'PUT', 'http.target': '/api/items/batch' } },
+                dynamoQuery(),
+                dynamoQuery(),
+                dynamoQuery(),
+                dynamoQuery(),
+                dynamoQuery(),
+            ],
+            // trace 2: 4 GET /items, no batch, 2 dynamo
+            [
+                clientHttp('/api/items'),
+                clientHttp('/api/items'),
+                clientHttp('/api/items'),
+                clientHttp('/api/items'),
+                dynamoQuery(),
+                dynamoQuery(),
+            ],
+            // trace 3: empty action subtree
+            [],
+            // trace 4: 1 GET /items
+            [clientHttp('/api/items')],
+        ];
+        const result = (0, aggregate_1.aggregate)({ perTraceDescendants: perTrace });
+        expect(result.traceCount).toBe(4);
+        const items = result.buckets.find((b) => b.key.category === 'http_direct' && b.key.operation === 'GET /api/items');
+        expect(items).toBeDefined();
+        // counts vector [2,4,0,1] sorted [0,1,2,4]; nearest-rank p50=1, p95=4.
+        expect(items.median).toBe(1);
+        expect(items.p95).toBe(4);
+        expect(items.max).toBe(4);
+        expect(items.coverage).toBeCloseTo(0.75, 5);
+        const dynamo = result.buckets.find((b) => b.key.category === 'dynamodb');
+        expect(dynamo).toBeDefined();
+        // [5,2,0,0] sorted [0,0,2,5]; nearest-rank p50=0, p95=5.
+        expect(dynamo.median).toBe(0);
+        expect(dynamo.p95).toBe(5);
+        expect(dynamo.max).toBe(5);
+        expect(dynamo.coverage).toBeCloseTo(0.5, 5);
+    });
+    it('skips SERVER spans (classified to null)', () => {
+        const result = (0, aggregate_1.aggregate)({
+            perTraceDescendants: [
+                [
+                    {
+                        name: 'GET /prod/api/items',
+                        traceId: 't',
+                        spanId: 's',
+                        parentSpanId: '',
+                        kind: 2,
+                        startNs: 0n,
+                        endNs: 0n,
+                        durationNs: 0n,
+                        attrs: { 'http.request.method': 'GET', 'http.target': '/api/items' },
+                        resourceAttrs: {},
+                    },
+                ],
+            ],
+        });
+        expect(result.buckets).toHaveLength(0);
+    });
+});

package/dist/helpers/event-workflow-impact/classify.d.ts

@@ -0,0 +1,13 @@
+import { FlatSpan } from '../../api/dash0/types';
+export type Category = 'http_direct' | 'http_transitive' | 'opensearch' | 'dynamodb' | 's3' | 'timestream' | 'lambda' | 'other';
+export declare const CATEGORY_ORDER: Category[];
+export declare const CATEGORY_LABEL: Record<Category, string>;
+export interface Classified {
+    category: Category;
+    service: string;
+    operation: string;
+}
+export declare function classifySpan(span: FlatSpan): Classified | null;
+export declare function templatePath(target: string): string;
+export declare function looksLikeId(seg: string): boolean;
+export declare function normalizeRouteName(name: string): string;