Skip to content

Commit cd7e106

Browse files
a-a-ka-a-k
committed
feat: add v1 stochastic connectivity contract
1 parent c12d63b commit cd7e106

50 files changed

Lines changed: 2999 additions & 241 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Makefile‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1+
ifeq ($(OS),Windows_NT)
2+
POSIX_SH ?= C:/Program Files/Git/usr/bin/sh.exe
3+
SHELL := $(POSIX_SH)
4+
else
15
SHELL := /bin/sh
6+
endif
27

38
GO ?= go
49
GORELEASER ?= goreleaser
@@ -18,6 +23,24 @@ BOOL_TRUE := 1 true TRUE yes YES
1823

1924
.PHONY: help lint test build run-checks docker-build goreleaser-release contracts-pack chart-package oci-image release-manifest validate-release release-dry-run release-local clean
2025

26+
ifeq ($(OS),Windows_NT)
27+
define MKDIR_P
28+
powershell -NoProfile -Command "New-Item -ItemType Directory -Force '$(1)' | Out-Null"
29+
endef
30+
31+
define RM_RF
32+
powershell -NoProfile -Command "if (Test-Path '$(1)') { Remove-Item -Recurse -Force '$(1)' }"
33+
endef
34+
else
35+
define MKDIR_P
36+
mkdir -p $(1)
37+
endef
38+
39+
define RM_RF
40+
rm -rf $(1)
41+
endef
42+
endif
43+
2144
help:
2245
@echo "Targets:"
2346
@echo " lint Run gofmt and go vet"
@@ -33,7 +56,7 @@ help:
3356
@echo " clean Remove generated binaries and release artifacts"
3457

3558
lint:
36-
@fmt_out="$$(gofmt -l .)"; \
59+
@fmt_out="$$(gofmt -l $$(git ls-files -co --exclude-standard -- '*.go'))"; \
3760
if [ -n "$$fmt_out" ]; then \
3861
echo "gofmt required for:"; \
3962
echo "$$fmt_out"; \
@@ -45,7 +68,7 @@ test:
4568
$(GO) test ./...
4669

4770
build:
48-
mkdir -p bin
71+
$(call MKDIR_P,bin)
4972
$(GO) build -trimpath -o bin/bering ./cmd/bering
5073

5174
run-checks: lint test build
@@ -54,7 +77,7 @@ docker-build:
5477
docker build -f build/Dockerfile -t $(IMAGE) .
5578

5679
goreleaser-release:
57-
rm -rf $(DIST_DIR)
80+
$(call RM_RF,$(DIST_DIR))
5881
RELEASE_VERSION=$(VERSION) $(GORELEASER) release --snapshot --clean --skip=publish
5982

6083
contracts-pack:
@@ -77,4 +100,6 @@ release-dry-run: lint test goreleaser-release contracts-pack chart-package oci-i
77100
release-local: test goreleaser-release contracts-pack chart-package oci-image release-manifest validate-release
78101

79102
clean:
80-
rm -rf bin out dist
103+
$(call RM_RF,bin)
104+
$(call RM_RF,out)
105+
$(call RM_RF,dist)

‎README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -150,25 +150,27 @@ go run ./cmd/sheaft run \
150150
--seed 42
151151
```
152152

153+
For Sheaft `v1.0.0` stochastic-connectivity compatibility, use the canonical fixture checkpoint in [examples/compatibility/sheaft-v1](examples/compatibility/sheaft-v1/README.md). It pins Bering `v0.3.4` / schema line `1.1.0` and includes model and snapshot artifacts with reliability evidence, observed edge metadata, and immediate/eventual endpoint semantic hints.
154+
153155
## Published Artifacts
154156

155157
### Core model
156158

157159
- `name`: `io.mb3r.bering.model`
158160
- `version`: `1.1.0`
159161
- `uri`: `https://mb3r-lab.github.io/Bering/schema/model/v1.1.0/model.schema.json`
160-
- `digest`: `sha256:bc9a60736c9e6bda9599243fd68f293b88f42ade65321d8267369a5c3214779a`
162+
- `digest`: `sha256:76b2b22422b6e64f437fb144a02b6bd4629bf510cec5479a8496c41eb25fc406`
161163

162-
This is the stable topology artifact intended for file-based consumers and tools such as Sheaft. It now carries first-class edge ids, typed service placement and shared-fate metadata, typed edge resilience policy, optional observed edge timing summaries, policy scope metadata, and richer endpoint fidelity.
164+
This is the stable topology artifact intended for file-based consumers and tools such as Sheaft. It now carries first-class operation-aware edge ids, typed service placement and shared-fate metadata, optional service/placement/edge reliability evidence, typed edge resilience policy, optional observed edge timing summaries, policy scope metadata, richer endpoint fidelity, and endpoint semantic hints.
163165

164166
### Snapshot envelope
165167

166168
- `name`: `io.mb3r.bering.snapshot`
167169
- `version`: `1.1.0`
168170
- `uri`: `https://mb3r-lab.github.io/Bering/schema/snapshot/v1.1.0/snapshot.schema.json`
169-
- `digest`: `sha256:53b127608b2aaa4fabb352b998cd6b2c5ed558764729a09abea56f4f9b40fa01`
171+
- `digest`: `sha256:c669dbc483ca8cfe1f58f994b6041a6767fdaa3df4fb5ae27d8253607b3f5cb5`
170172

171-
This wraps the model with runtime window metadata, ingest counts, coverage, provenance, topology diffs, and discovery-side copies of the same typed placement, resilience, and observed edge metadata.
173+
This wraps the model with runtime window metadata, ingest counts, coverage, provenance, topology diffs, and discovery-side copies of the same typed placement, reliability, resilience, observed edge, and endpoint metadata.
172174

173175
### Signal quality report
174176

@@ -188,9 +190,9 @@ These runtime views do not change the public `io.mb3r.bering.model@1.1.0` or `io
188190

189191
### Population Today
190192

191-
- `topology_api` input and discovery overlays are the first-class write surfaces for typed `placements`, `shared_resource_refs`, `resilience`, `observed`, `policy_scope`, and richer endpoint metadata.
192-
- Trace discovery can derive stable edge ids, endpoint `method` and `path`, and `observed.latency_ms.*` summaries when span timing exists.
193-
- Generic trace ingestion does not currently infer timeout policies, retry policies, circuit-breaker settings, placement groups, or shared resource references. Those remain out of scope for Bering trace inference today.
193+
- `topology_api` input and discovery overlays are the first-class write surfaces for typed `placements`, `shared_resource_refs`, `reliability`, `resilience`, `observed`, `policy_scope`, and richer endpoint metadata, including `metadata.semantics`.
194+
- Trace discovery can derive operation-aware stable edge ids, endpoint `method` and `path`, and `observed.latency_ms.*` summaries when span timing exists.
195+
- Generic trace ingestion does not currently infer timeout policies, retry policies, circuit-breaker settings, placement groups, shared resource references, or endpoint success semantics. Those remain out of scope for Bering trace inference today.
194196

195197
## Release Packaging
196198

@@ -217,6 +219,7 @@ Release outputs include:
217219
- Topology input: [examples/topology/topology-api.sample.yaml](examples/topology/topology-api.sample.yaml)
218220
- Batch outputs: [examples/outputs/bering-model.normalized.sample.json](examples/outputs/bering-model.normalized.sample.json), [examples/outputs/bering-snapshot.normalized.sample.json](examples/outputs/bering-snapshot.normalized.sample.json), [examples/outputs/bering-model.topology-api.sample.json](examples/outputs/bering-model.topology-api.sample.json), [examples/outputs/bering-snapshot.topology-api.sample.json](examples/outputs/bering-snapshot.topology-api.sample.json)
219221
- Adapter-generated outputs: [examples/outputs/bering-model.service-catalog-adapter.sample.json](examples/outputs/bering-model.service-catalog-adapter.sample.json), [examples/outputs/bering-snapshot.service-catalog-adapter.sample.json](examples/outputs/bering-snapshot.service-catalog-adapter.sample.json)
222+
- Sheaft v1 compatibility fixtures: [examples/compatibility/sheaft-v1](examples/compatibility/sheaft-v1/README.md)
220223
- Runtime config: [configs/serve.sample.yaml](configs/serve.sample.yaml)
221224
- Discovery overlay: [configs/discovery.overlay.sample.yaml](configs/discovery.overlay.sample.yaml)
222225
- Enrichment onboarding: [examples/enrichment](examples/enrichment/README.md)

‎api/schema/model/v1.1.0/model.schema.json‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,25 @@
6868
}
6969
}
7070
},
71+
"edgeIdentity": {
72+
"type": "object",
73+
"properties": {
74+
"protocol": { "type": "string" },
75+
"operation": { "type": "string" },
76+
"route": { "type": "string" },
77+
"topic": { "type": "string" },
78+
"span_kind": { "type": "string" }
79+
}
80+
},
81+
"reliabilityEvidence": {
82+
"type": "object",
83+
"required": ["live_probability"],
84+
"properties": {
85+
"live_probability": { "type": "number", "minimum": 0, "maximum": 1 },
86+
"source": { "type": "string" },
87+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
88+
}
89+
},
7190
"placement": {
7291
"type": "object",
7392
"required": ["replicas"],
@@ -76,7 +95,8 @@
7695
"labels": {
7796
"type": "object",
7897
"additionalProperties": { "type": "string" }
79-
}
98+
},
99+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" }
80100
}
81101
},
82102
"serviceMetadata": {
@@ -85,6 +105,7 @@
85105
{
86106
"type": "object",
87107
"properties": {
108+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" },
88109
"failure_eligible": { "type": "boolean" },
89110
"placements": {
90111
"type": "array",
@@ -104,18 +125,44 @@
104125
{
105126
"type": "object",
106127
"properties": {
107-
"weight": { "type": "number", "minimum": 0 }
128+
"weight": { "type": "number", "minimum": 0 },
129+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" }
108130
}
109131
}
110132
]
111133
},
134+
"endpointSemantics": {
135+
"type": "object",
136+
"properties": {
137+
"predicate_mode": {
138+
"type": "string",
139+
"enum": ["immediate_response", "eventual_completion", "external_predicate"]
140+
},
141+
"mandatory_targets": {
142+
"type": "array",
143+
"items": { "type": "string" },
144+
"uniqueItems": true
145+
},
146+
"dependency_modes": {
147+
"type": "array",
148+
"items": {
149+
"type": "string",
150+
"enum": ["sync", "async"]
151+
},
152+
"uniqueItems": true
153+
},
154+
"source": { "type": "string" },
155+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
156+
}
157+
},
112158
"endpointMetadata": {
113159
"allOf": [
114160
{ "$ref": "#/$defs/commonMetadata" },
115161
{
116162
"type": "object",
117163
"properties": {
118-
"weight": { "type": "number", "minimum": 0 }
164+
"weight": { "type": "number", "minimum": 0 },
165+
"semantics": { "$ref": "#/$defs/endpointSemantics" }
119166
}
120167
}
121168
]
@@ -209,6 +256,7 @@
209256
"enum": ["sync", "async"]
210257
},
211258
"blocking": { "type": "boolean" },
259+
"identity": { "$ref": "#/$defs/edgeIdentity" },
212260
"metadata": { "$ref": "#/$defs/edgeMetadata" },
213261
"resilience": { "$ref": "#/$defs/resiliencePolicy" },
214262
"observed": { "$ref": "#/$defs/observedEdge" },

‎api/schema/snapshot/v1.1.0/snapshot.schema.json‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,25 @@
211211
}
212212
}
213213
},
214+
"edgeIdentity": {
215+
"type": "object",
216+
"properties": {
217+
"protocol": { "type": "string" },
218+
"operation": { "type": "string" },
219+
"route": { "type": "string" },
220+
"topic": { "type": "string" },
221+
"span_kind": { "type": "string" }
222+
}
223+
},
224+
"reliabilityEvidence": {
225+
"type": "object",
226+
"required": ["live_probability"],
227+
"properties": {
228+
"live_probability": { "type": "number", "minimum": 0, "maximum": 1 },
229+
"source": { "type": "string" },
230+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
231+
}
232+
},
214233
"discoveryCommonMetadata": {
215234
"allOf": [
216235
{ "$ref": "#/$defs/commonMetadata" },
@@ -233,7 +252,8 @@
233252
"labels": {
234253
"type": "object",
235254
"additionalProperties": { "type": "string" }
236-
}
255+
},
256+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" }
237257
}
238258
},
239259
"serviceMetadata": {
@@ -242,6 +262,7 @@
242262
{
243263
"type": "object",
244264
"properties": {
265+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" },
245266
"failure_eligible": { "type": "boolean" },
246267
"placements": {
247268
"type": "array",
@@ -261,6 +282,7 @@
261282
{
262283
"type": "object",
263284
"properties": {
285+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" },
264286
"failure_eligible": { "type": "boolean" },
265287
"replicas_override": { "type": "integer", "minimum": 0 },
266288
"placements": {
@@ -281,7 +303,8 @@
281303
{
282304
"type": "object",
283305
"properties": {
284-
"weight": { "type": "number", "minimum": 0 }
306+
"weight": { "type": "number", "minimum": 0 },
307+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" }
285308
}
286309
}
287310
]
@@ -292,18 +315,44 @@
292315
{
293316
"type": "object",
294317
"properties": {
295-
"weight": { "type": "number", "minimum": 0 }
318+
"weight": { "type": "number", "minimum": 0 },
319+
"reliability": { "$ref": "#/$defs/reliabilityEvidence" }
296320
}
297321
}
298322
]
299323
},
324+
"endpointSemantics": {
325+
"type": "object",
326+
"properties": {
327+
"predicate_mode": {
328+
"type": "string",
329+
"enum": ["immediate_response", "eventual_completion", "external_predicate"]
330+
},
331+
"mandatory_targets": {
332+
"type": "array",
333+
"items": { "type": "string" },
334+
"uniqueItems": true
335+
},
336+
"dependency_modes": {
337+
"type": "array",
338+
"items": {
339+
"type": "string",
340+
"enum": ["sync", "async"]
341+
},
342+
"uniqueItems": true
343+
},
344+
"source": { "type": "string" },
345+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
346+
}
347+
},
300348
"endpointMetadata": {
301349
"allOf": [
302350
{ "$ref": "#/$defs/commonMetadata" },
303351
{
304352
"type": "object",
305353
"properties": {
306-
"weight": { "type": "number", "minimum": 0 }
354+
"weight": { "type": "number", "minimum": 0 },
355+
"semantics": { "$ref": "#/$defs/endpointSemantics" }
307356
}
308357
}
309358
]
@@ -315,6 +364,7 @@
315364
"type": "object",
316365
"properties": {
317366
"weight": { "type": "number", "minimum": 0 },
367+
"semantics": { "$ref": "#/$defs/endpointSemantics" },
318368
"predicate_ref": { "type": "string" }
319369
}
320370
}
@@ -413,6 +463,7 @@
413463
"to": { "type": "string" },
414464
"kind": { "type": "string", "enum": ["sync", "async"] },
415465
"blocking": { "type": "boolean" },
466+
"identity": { "$ref": "#/$defs/edgeIdentity" },
416467
"support": { "$ref": "#/$defs/support" },
417468
"first_seen": { "type": "string", "format": "date-time" },
418469
"last_seen": { "type": "string", "format": "date-time" },
@@ -463,6 +514,7 @@
463514
"to": { "type": "string" },
464515
"kind": { "type": "string", "enum": ["sync", "async"] },
465516
"blocking": { "type": "boolean" },
517+
"identity": { "$ref": "#/$defs/edgeIdentity" },
466518
"metadata": { "$ref": "#/$defs/edgeMetadata" },
467519
"resilience": { "$ref": "#/$defs/resiliencePolicy" },
468520
"observed": { "$ref": "#/$defs/observedEdge" },

0 commit comments

Comments
 (0)