@scoutflo/alert-correlation

Pure alert-to-topology correlation contracts and policies for Scoutflo alert investigation workflows.

This package intentionally owns only shared contracts, extraction, matching, scoring, and decision logic. Provider detail fetching, tenant authorization, topology loading, topology slice construction, and API response shaping stay in Gateway. Investigation lifecycle and supervisor startup stay in Voyager.

Relationship To Correlation Core

Reusable cross-mode contracts live in @scoutflo/correlation-core.

@scoutflo/alert-correlation remains alert-specific. It owns AlertRef, alert time windows, provider alert extractors, alert-to-topology matching, alert-specific scoring, and alert decision behavior.

This package consumes core entity, fact, and status primitives where safe. It also exports correlationCore as a namespace for compatibility during migration, without replacing existing alert-specific export names.

Version

Current package version: 0.2.1.

Gateway and Voyager should consume the exact published version:

"@scoutflo/alert-correlation": "0.2.1"

During local development, consumers may temporarily use a file: dependency pointed at ../integration-sdk/packages/alert-correlation, then replace it with the exact npm version before release.

Correlation Semantics

This package treats provider facts as evidence, not canonical topology identity. Provider-specific extractors should preserve source keys exactly when the key has operational meaning.

Important matching rules:

• service_name and service are distinct facts.
• Topology relationship attribute serviceName matches explicit service-name facts such as service_name, serviceName, and service.name.
• Topology relationship attribute serviceLabel matches generic Prometheus-style service labels.
• Workload ownership evidence such as deployment, pod, container, and namespace outranks monitoring backend exporter labels.
• Trace evidence such as service_name, http_route, http_status_code, http_method, trace_id, span_id, span_kind, and env is preserved for provider-aware matching.
• Prometheus-compatible extractors preserve grouped alert common labels/annotations and per-alert labels/annotations.
• Prometheus-compatible extractors include rule/query/evaluation facts such as rule.name, rule.query, expr, query, for, activeAt, lastEvaluation, value, and alertstate.
• The Sentry extractor includes issue, project/org, metadata, SDK, release, transaction, latest-event, and trace identity facts when present.

Release Flow

Use this flow when releasing only @scoutflo/alert-correlation. Do not publish the root @scoutflo/integration-sdk package for an alert-correlation-only release.

1. Local Preflight

Run the package build, package tests, root SDK build, and package dry run:

npm run build --workspace @scoutflo/alert-correlation
npm test --workspace @scoutflo/alert-correlation
npm run build
npm pack --dry-run --workspace @scoutflo/alert-correlation

If local npm cache permissions fail during npm pack --dry-run, use a repo-local temporary cache instead of changing global cache ownership:

mkdir -p .tmp/npm-cache
npm_config_cache=.tmp/npm-cache npm pack --dry-run --workspace @scoutflo/alert-correlation

2. Check The Registry

Before publishing, verify whether the exact version already exists:

npm view @scoutflo/alert-correlation@<version> version

If npm returns the version, do not publish again. If npm returns E404, the version is not visible from the current registry/auth context and can be published if release approval exists.

3. Publish This Workspace Only

Publish only the alert-correlation workspace:

npm publish --workspace @scoutflo/alert-correlation

Do not run npm publish from the repository root for this release.

4. Confirm The Published Version

After publish succeeds, confirm the exact version:

npm view @scoutflo/alert-correlation@<version> version

If npm view returns E404 immediately after a successful publish, wait and retry before moving consumers. This can indicate registry propagation delay, package visibility, or auth scope issues.

5. Roll Out To Consumers

After the version is visible, update Gateway and Voyager from any local file: dependency to the exact published version, for example:

"@scoutflo/alert-correlation": "0.2.1"

Run install and the relevant tests in each consumer repo after updating its dependency lockfile.

Open and merge PRs in dependency order:

1. integration-sdk
2. Gateway
3. Voyager
4. Client

Safety Notes

• Do not commit .npmrc.
• Do not publish root @scoutflo/integration-sdk when releasing only alert correlation.
• Do not reuse a version after npm publish succeeds; bump the package version for any follow-up release.
• Do not move Gateway or Voyager from local file: dependencies until the published package is visible with npm view.

The package is configured for public npm publishing through its publishConfig.