@scoutflo/topology-contracts 0.7.27 → 0.8.0

package/README.md

@@ -11,6 +11,53 @@ This package owns:
 - 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.
+
+## 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.