@scoutflo/topology-contracts

Pure shared topology vocabulary and Zod boundary schemas for Scoutflo topology workflows.

This package owns:

• topology provider constants and explicit compatibility aliases;
• AWS, Kubernetes, integration, and GitHub account topology family constants;
• GitHub account source-sync source-type constants;
• source-sync capability, intent, scope, completeness, warning, and candidate DTO schemas;
• topology correlation rule metadata and candidate DTO schemas;
• topology correlation contract endpoint, relation-class, family, and contract-key vocabulary;
• Gateway/Mongo-aligned topology resource and relation vocabulary constants useful at contract boundaries.
• the bounded, schema-validated Gateway-to-Voyager alertContext.topologyContext DTO.
• versioned, bounded Jira/JSM, Confluence, and Sentry product-key normalization that preserves raw evidence and provider scope.

Gateway alert topology context

topologySlice is the canonical topology reconstruction whenever it is present. When it is absent, legacy projections remain the compatibility fallback. The legacy investigationContext.investigationResources and investigationContext.relatedServices fields remain parseable for compatibility, but are deprecated derived projections and must not override or be merged back into topologySlice. Parsed legacy v1 payloads receive explicit compatibility metadata expressing that rule.

All context input passes an iterative preflight before recursive parsing: maximum depth 12, maximum 1,000 object/array nodes, maximum 1 MiB aggregate key/string content, and bounded map keys. Opaque legacy records remain extensible only inside that aggregate budget.

For untrusted recursive input, use gatewayTopologyContextSchema or nestedTopologyResponseSchema. Recursive node/child builders are intentionally not exported.

candidateTargets is a read-only transport projection of the authoritative alertCorrelationCandidate, not a second authoring model. It retains displayName for existing consumers and carries only correlation identity, confidence, bounded normalized evidence, and the same machine-readable reason-code semantics. Runtime discovery and provider behavior do not belong in this DTO. Typed diagnostics reports evidence and topology-slice availability/truncation; a producer may not claim truncation without reporting omitted evidence or a bounded truncation reason.

Existing confidence remains the backward-compatible decile score (current payloads use values such as 9). Producers that expose normalized confidence use normalizedConfidence, which is strictly bounded to 0..1; consumers must not silently reinterpret the legacy scale.

Release order for this contract is: publish @scoutflo/topology-contracts, update and publish @scoutflo/alert-correlation against that registry version, then update Gateway (producer) and Voyager (consumer). Consumers must not use file: dependencies. Gateway should validate the outbound field before Voyager makes it authoritative.

Runtime container provenance

runtime.container-provenance.v1 is a separate immutable evidence DTO shared by Kubernetes and Gateway. It preserves requested image, observed runtime image/image ID/digest, and pod-metadata source claims as distinct trust domains. claimed_source.status is only unverified or unavailable; an Argo target revision, image tag, or pod annotation is never promoted to verified runtime identity. Containers are bounded to 128 and must be deterministically sorted by regular, init, then ephemeral kind and name before truncation. Equal names in different kinds remain distinct. For compatibility, parsing supplies the v1 version when an older K8s payload omits it and accepts a missing containers_omitted; new K8s producers must emit both before this is treated as their validated shared wire format. Digests are lowercase sha256, sha384, or sha512 with exact hex lengths. Every unavailable, unverified, unknown, or inconsistent state carries a bounded reason.

Canonical topology resource and relation constants mirror stable persisted Scoutflo ontology values. Source-sync family constants remain separate and may use provider/source-specific family names such as AWS scan families.

GitHub source-sync vocabulary currently covers only the account/App installation node (account family and github_account source type). Repository inventory and repository relationship vocabulary are intentionally not exported yet.

Provider constants are shared vocabulary, not a source-sync capability registry. Values such as pagerduty and correlation may be valid persisted providers without implying that the source-sync registry can run them.

Gateway remains the runtime authority for provider discovery, credential resolution, dry-run/apply, lifecycle, reconciliation, persistence, audit, provider clients, source-specific payload parsing, and topology correlation rule execution.

k8s is the persisted Kubernetes provider key. kubernetes is accepted only through the explicit alias normalization helper.