Generate contract types, pin fixtures to spec, add build and ADRs
Some checks failed
ci / build (push) Failing after 1m6s
Some checks failed
ci / build (push) Failing after 1m6s
Completes FLUID-WP-0002. The record types in internal/contract are generated from schemas/ by a dependency-free generator; fixtures transcribed from the spec's worked examples validate against those schemas and round-trip through the generated types with DisallowUnknownFields, so a spec change that misses the schemas fails CI rather than drifting silently. Adds identifier prefix helpers, Makefile, GitHub Actions, and five ADRs recording the Go choice, out-of-process attachment, the wire contract as boundary, the evidence store, and revision identity. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014KmVxhJ35tCo7rE7UnLwWu Assistant: claude-code Assistant-Model: opus Assistant-Process: 1116572@bnt-lap001 Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400
This commit is contained in:
parent
fbbf56df7a
commit
76912adef8
44 changed files with 4010 additions and 7 deletions
38
conformance/fixtures/json/backend-requirement.json
Normal file
38
conformance/fixtures/json/backend-requirement.json
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
{
|
||||
"fluid_backend_requirement": {
|
||||
"backend_service": "payments-service",
|
||||
"capability": {
|
||||
"description": "Retrieve payment state as of a specified timestamp.\n",
|
||||
"title": "Historical payment-state query"
|
||||
},
|
||||
"disposition": {
|
||||
"reason": null,
|
||||
"state": "PLANNED",
|
||||
"target_ref": "payments-service/roadmap#412"
|
||||
},
|
||||
"expected_usage": {
|
||||
"requests_per_day": 120000
|
||||
},
|
||||
"id": "BR-0041",
|
||||
"originating_hypothesis": "H-0212",
|
||||
"originating_interface": "customer-context-api",
|
||||
"originating_revision": "R-0081",
|
||||
"quality": {
|
||||
"availability": 0.999,
|
||||
"p95_latency_ms": 250
|
||||
},
|
||||
"schema_version": "0.1",
|
||||
"security": {
|
||||
"authorization_scope": "payments.read",
|
||||
"tenant_isolation": "required"
|
||||
},
|
||||
"semantics": {
|
||||
"consistency": "snapshot",
|
||||
"required_fields": [
|
||||
"payment_id",
|
||||
"state",
|
||||
"effective_at"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
22
conformance/fixtures/json/event.json
Normal file
22
conformance/fixtures/json/event.json
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
{
|
||||
"fluid_event": {
|
||||
"actor": {
|
||||
"id": "fluid-daimon/customer-finance-api",
|
||||
"type": "daimon"
|
||||
},
|
||||
"entity_id": "R-000221",
|
||||
"entity_type": "revision",
|
||||
"event_type": "PROMOTION_RECOMMENDED",
|
||||
"evidence_refs": [
|
||||
"metrics:E-000093/window-4"
|
||||
],
|
||||
"id": "EV-990281",
|
||||
"inputs": [
|
||||
"H-000184",
|
||||
"E-000093"
|
||||
],
|
||||
"occurred_at": "2026-09-09T11:31:02Z",
|
||||
"reason": "Candidate met primary success target and violated no guardrails.\n",
|
||||
"schema_version": "0.1"
|
||||
}
|
||||
}
|
||||
44
conformance/fixtures/json/experiment.json
Normal file
44
conformance/fixtures/json/experiment.json
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
{
|
||||
"fluid_experiment": {
|
||||
"allocation": {
|
||||
"candidate": 0.28,
|
||||
"control": 0.72
|
||||
},
|
||||
"candidate_revisions": [
|
||||
"R-000221"
|
||||
],
|
||||
"cohorts": [
|
||||
"partner-integrations",
|
||||
"coding-agents"
|
||||
],
|
||||
"control_revision": "R-000220",
|
||||
"hypothesis_refs": [
|
||||
"H-000184"
|
||||
],
|
||||
"id": "E-000093",
|
||||
"interface_id": "customer-finance-api",
|
||||
"metrics": {
|
||||
"guardrails": [
|
||||
"p95_latency_ms",
|
||||
"error_rate",
|
||||
"authorization_scope_change"
|
||||
],
|
||||
"primary": [
|
||||
"requests_per_completed_task"
|
||||
]
|
||||
},
|
||||
"planned_end_at": "2026-10-05T08:00:00Z",
|
||||
"result": {
|
||||
"evidence_refs": [],
|
||||
"preferred_revision": null,
|
||||
"state": "RUNNING"
|
||||
},
|
||||
"schema_version": "0.1",
|
||||
"start_at": "2026-09-05T08:00:00Z",
|
||||
"stop_conditions": [
|
||||
"hard_guardrail_violation",
|
||||
"security_failure",
|
||||
"manual_stop"
|
||||
]
|
||||
}
|
||||
}
|
||||
26
conformance/fixtures/json/feedback.json
Normal file
26
conformance/fixtures/json/feedback.json
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
{
|
||||
"fluid_feedback": {
|
||||
"attempted_operations": [
|
||||
"list-transactions",
|
||||
"get-balances"
|
||||
],
|
||||
"cohort": "coding-agents",
|
||||
"confidence": 0.94,
|
||||
"goal": "produce monthly account statement",
|
||||
"id": "F-9821",
|
||||
"impact": {
|
||||
"calls": 18,
|
||||
"latency_ms": 2810
|
||||
},
|
||||
"interface_id": "customer-finance-api",
|
||||
"missing_capability": "consolidated-period-summary",
|
||||
"outcome": "capability unavailable",
|
||||
"received_at": "2026-08-28T09:12:00Z",
|
||||
"revision": "R-000220",
|
||||
"schema_version": "0.1",
|
||||
"workaround": [
|
||||
"aggregate-locally",
|
||||
"infer-closing-balance"
|
||||
]
|
||||
}
|
||||
}
|
||||
164
conformance/fixtures/json/hypothesis.json
Normal file
164
conformance/fixtures/json/hypothesis.json
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
{
|
||||
"fluid_hypothesis": {
|
||||
"audit": {
|
||||
"decision_refs": [
|
||||
"D-2811"
|
||||
],
|
||||
"immutable_event_refs": [
|
||||
"EV-990218"
|
||||
]
|
||||
},
|
||||
"backend_requirements": {
|
||||
"required": false,
|
||||
"requirement_refs": []
|
||||
},
|
||||
"candidate_revision_refs": [
|
||||
"R-000221"
|
||||
],
|
||||
"complexity": {
|
||||
"expected_delta": {
|
||||
"cognitive_load": -0.2,
|
||||
"concept_count": 0,
|
||||
"operation_count": 1,
|
||||
"semantic_overlap": 0.1,
|
||||
"surface_area": 1
|
||||
},
|
||||
"score": 0.18
|
||||
},
|
||||
"created_at": "2026-09-04T12:00:00Z",
|
||||
"created_by": {
|
||||
"id": "fluid-daimon/customer-finance-api",
|
||||
"type": "daimon"
|
||||
},
|
||||
"economics": {
|
||||
"currency": "EUR",
|
||||
"estimated_experiment_cost": 18.0,
|
||||
"estimated_implementation_cost": 40.0,
|
||||
"expected_value_class": "MEDIUM"
|
||||
},
|
||||
"expected_outcomes": [
|
||||
{
|
||||
"baseline": 2.7,
|
||||
"cohort": "all",
|
||||
"direction": "lower",
|
||||
"metric": "requests_per_completed_task",
|
||||
"target": 1.2
|
||||
},
|
||||
{
|
||||
"baseline": 1.0,
|
||||
"cohort": "all",
|
||||
"direction": "lower",
|
||||
"metric": "client_side_sort_workarounds",
|
||||
"target": 0.2
|
||||
}
|
||||
],
|
||||
"experiment_refs": [
|
||||
"E-000093"
|
||||
],
|
||||
"explanation": {
|
||||
"claim": "Consumers treat \"latest invoice\" as a domain-level concept and the existing generic collection interface does not present that concept directly.\n",
|
||||
"reach": {
|
||||
"explains": [
|
||||
"P-1831",
|
||||
"P-1834"
|
||||
],
|
||||
"notes": "Medium reach: explains several related request patterns but not broader financial-context pressure.\n",
|
||||
"score": 0.42
|
||||
}
|
||||
},
|
||||
"failure_criteria": {
|
||||
"expression": "any hard guardrail violation OR adoption below 5% after 30 days when equally discoverable\n"
|
||||
},
|
||||
"fitness_dimensions": {
|
||||
"expected": {
|
||||
"client_utility": 0.7,
|
||||
"compatibility": 0.0,
|
||||
"correctness": 0.0,
|
||||
"discoverability": 0.65,
|
||||
"maintainability": -0.05,
|
||||
"operational_cost": 0.0,
|
||||
"performance": 0.1,
|
||||
"reliability": 0.0,
|
||||
"security": 0.0,
|
||||
"simplicity": -0.15
|
||||
}
|
||||
},
|
||||
"guardrails": [
|
||||
{
|
||||
"metric": "p95_latency_ms",
|
||||
"operator": "<=",
|
||||
"threshold": 315
|
||||
},
|
||||
{
|
||||
"metric": "authorization_scope_change",
|
||||
"operator": "==",
|
||||
"threshold": false
|
||||
},
|
||||
{
|
||||
"metric": "backend_query_count_delta",
|
||||
"operator": "<=",
|
||||
"threshold": 0
|
||||
}
|
||||
],
|
||||
"id": "H-000184",
|
||||
"interface_id": "customer-finance-api",
|
||||
"learning_value": {
|
||||
"notes": "Useful signal for whether first-class convenience resources improve agent and partner integration behavior.\n",
|
||||
"score": 0.56
|
||||
},
|
||||
"observation": {
|
||||
"affected_cohorts": [
|
||||
"partner-integrations",
|
||||
"coding-agents"
|
||||
],
|
||||
"evidence_refs": [
|
||||
"telemetry:invoice-pattern-2026w36",
|
||||
"feedback:F-9821"
|
||||
],
|
||||
"observation_window": {
|
||||
"end": "2026-09-01T00:00:00Z",
|
||||
"start": "2026-08-15T00:00:00Z"
|
||||
},
|
||||
"summary": "A significant consumer cohort retrieves invoice collections, sorts them by issue date, and discards all but the first item.\n"
|
||||
},
|
||||
"outcome": {
|
||||
"evidence_refs": [],
|
||||
"status": null,
|
||||
"summary": null
|
||||
},
|
||||
"pressure": {
|
||||
"classes": [
|
||||
"successful_but_inefficient_usage",
|
||||
"repeated_expectation_mismatch"
|
||||
],
|
||||
"confidence": 0.88,
|
||||
"severity": 0.61
|
||||
},
|
||||
"priority": {
|
||||
"decided_by": "optimization-policy-v3",
|
||||
"score": 0.71
|
||||
},
|
||||
"proposed_adaptation": {
|
||||
"candidate_contract": {
|
||||
"method": "GET",
|
||||
"path": "/customers/{id}/invoices/latest"
|
||||
},
|
||||
"class": "contract",
|
||||
"implementation_scope": "interface_only",
|
||||
"summary": "Add an explicit latest-invoice retrieval capability.\n"
|
||||
},
|
||||
"risk": {
|
||||
"level": "LOW",
|
||||
"reasons": [
|
||||
"read-only operation",
|
||||
"no authorization expansion"
|
||||
]
|
||||
},
|
||||
"schema_version": "0.1",
|
||||
"state": "PRIORITIZED",
|
||||
"success_criteria": {
|
||||
"expression": "requests_per_completed_task <= 1.2 AND no hard guardrail violation\n"
|
||||
},
|
||||
"title": "Provide direct latest-invoice capability"
|
||||
}
|
||||
}
|
||||
25
conformance/fixtures/json/pressure.json
Normal file
25
conformance/fixtures/json/pressure.json
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
{
|
||||
"fluid_pressure": {
|
||||
"affected_cohorts": [
|
||||
"partner-integrations"
|
||||
],
|
||||
"class": "successful_but_inefficient_usage",
|
||||
"evidence_refs": [
|
||||
"telemetry:query-pattern-712"
|
||||
],
|
||||
"first_seen": "2026-08-15T10:11:00Z",
|
||||
"frequency": {
|
||||
"independent_consumers": 83,
|
||||
"observations": 1740
|
||||
},
|
||||
"id": "P-1831",
|
||||
"interface_id": "customer-finance-api",
|
||||
"last_seen": "2026-09-01T12:15:00Z",
|
||||
"linked_hypotheses": [
|
||||
"H-000184"
|
||||
],
|
||||
"schema_version": "0.1",
|
||||
"status": "OPEN",
|
||||
"summary": "Consumers repeatedly retrieve complete invoice collections to determine the latest invoice.\n"
|
||||
}
|
||||
}
|
||||
35
conformance/fixtures/json/revision-descriptor.json
Normal file
35
conformance/fixtures/json/revision-descriptor.json
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
{
|
||||
"revision": {
|
||||
"contract": {
|
||||
"digest": "sha256:3b1f9c2e7a4d8b6051e2c9f0a7d4b83e15c6f2a9d0b7e4c1836a5f2d9c0b7e41",
|
||||
"source": "artifact:openapi/customer-finance-api/r22",
|
||||
"type": "openapi"
|
||||
},
|
||||
"id": "R-000221",
|
||||
"intent": {
|
||||
"version": "IEI-7"
|
||||
},
|
||||
"interface": "customer-finance-api",
|
||||
"policy": {
|
||||
"compatibility": "additive",
|
||||
"policy_check": "passed",
|
||||
"rollback_to": "R-000220",
|
||||
"security_check": "passed"
|
||||
},
|
||||
"routing": {
|
||||
"eligible_cohorts": [
|
||||
"partner-integrations",
|
||||
"coding-agents"
|
||||
],
|
||||
"max_traffic_share": 0.3
|
||||
},
|
||||
"runtime": {
|
||||
"digest": "sha256:3b1f9c2e7a4d8b6051e2c9f0a7d4b83e15c6f2a9d0b7e4c1836a5f2d9c0b7e41",
|
||||
"image": "registry/fluid/customer-finance:R-42",
|
||||
"timeout_ms": 5000,
|
||||
"upstream": "http://adapter-r22.fluid-runtime.svc:8080"
|
||||
},
|
||||
"schema_version": "0.1",
|
||||
"state": "candidate"
|
||||
}
|
||||
}
|
||||
150
conformance/fixtures/json/revision.json
Normal file
150
conformance/fixtures/json/revision.json
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
{
|
||||
"fluid_revision": {
|
||||
"adaptation_classes": [
|
||||
"contract"
|
||||
],
|
||||
"adoption": {
|
||||
"active_consumers": 119,
|
||||
"adoption_rate": 0.289,
|
||||
"eligible_consumers": 412,
|
||||
"retained_adoption_rate": null
|
||||
},
|
||||
"audit": {
|
||||
"immutable_event_refs": [
|
||||
"EV-990221",
|
||||
"EV-990244",
|
||||
"EV-990281"
|
||||
]
|
||||
},
|
||||
"backend_requirements": [],
|
||||
"compatibility": {
|
||||
"breaking_changes": [],
|
||||
"class": "BACKWARD_COMPATIBLE",
|
||||
"compatibility_evidence_refs": [
|
||||
"test:compat-suite-775"
|
||||
],
|
||||
"deprecations": [],
|
||||
"supersedes": []
|
||||
},
|
||||
"complexity": {
|
||||
"after": {
|
||||
"operation_count": 40,
|
||||
"surface_area": 42
|
||||
},
|
||||
"before": {
|
||||
"operation_count": 39,
|
||||
"surface_area": 41
|
||||
},
|
||||
"budget_status": "WITHIN_BUDGET",
|
||||
"delta_score": 0.18
|
||||
},
|
||||
"contract": {
|
||||
"artifact_ref": "artifact:openapi/customer-finance-api/r22",
|
||||
"digest": "sha256:3b1f9c2e7a4d8b6051e2c9f0a7d4b83e15c6f2a9d0b7e4c1836a5f2d9c0b7e41",
|
||||
"type": "openapi",
|
||||
"version": "3.1"
|
||||
},
|
||||
"created_at": "2026-09-04T13:10:00Z",
|
||||
"created_by": {
|
||||
"id": "fluid-daimon/customer-finance-api",
|
||||
"type": "daimon"
|
||||
},
|
||||
"deployment": {
|
||||
"current_exposure": {
|
||||
"cohorts": [
|
||||
"partner-integrations",
|
||||
"coding-agents"
|
||||
],
|
||||
"traffic_share": 0.28
|
||||
},
|
||||
"environments": [
|
||||
{
|
||||
"name": "production",
|
||||
"routing_policy_ref": "route-policy:rp-118",
|
||||
"started_at": "2026-09-05T08:00:00Z"
|
||||
}
|
||||
]
|
||||
},
|
||||
"economics": {
|
||||
"build_cost": 38.2,
|
||||
"currency": "EUR",
|
||||
"experiment_cost_to_date": 12.4
|
||||
},
|
||||
"fitness": {
|
||||
"baseline_revision": "R-000220",
|
||||
"measurement_window": {
|
||||
"end": null,
|
||||
"start": "2026-09-05T08:00:00Z"
|
||||
},
|
||||
"metrics": {
|
||||
"error_rate": {
|
||||
"baseline": 0.008,
|
||||
"current": 0.007
|
||||
},
|
||||
"p95_latency_ms": {
|
||||
"baseline": 300,
|
||||
"current": 302,
|
||||
"guardrail": 315
|
||||
},
|
||||
"requests_per_completed_task": {
|
||||
"baseline": 2.7,
|
||||
"current": 1.15,
|
||||
"target": 1.2
|
||||
}
|
||||
}
|
||||
},
|
||||
"id": "R-000221",
|
||||
"implementation": {
|
||||
"artifact_ref": "artifact:adapter/customer-finance-api/r22",
|
||||
"build_ref": "build:8871",
|
||||
"digest": "sha256:3b1f9c2e7a4d8b6051e2c9f0a7d4b83e15c6f2a9d0b7e4c1836a5f2d9c0b7e41",
|
||||
"source_ref": "git:9f4c2ab"
|
||||
},
|
||||
"interface_evolution_intent": {
|
||||
"artifact_ref": "artifact:intent/customer-finance-api/IEI-7",
|
||||
"version": "IEI-7"
|
||||
},
|
||||
"interface_id": "customer-finance-api",
|
||||
"originating_hypotheses": [
|
||||
"H-000184"
|
||||
],
|
||||
"parent_revision": "R-000220",
|
||||
"promotion": {
|
||||
"authorized_at": null,
|
||||
"authorized_by": null,
|
||||
"eligible": true,
|
||||
"recommendation_reason": "Target fitness reached with no guardrail violations.\n",
|
||||
"recommended_state": "STABLE"
|
||||
},
|
||||
"provenance": {
|
||||
"decision_refs": [
|
||||
"D-2811"
|
||||
],
|
||||
"experiment_refs": [
|
||||
"E-000093"
|
||||
],
|
||||
"telemetry_refs": [
|
||||
"telemetry:invoice-pattern-2026w36"
|
||||
]
|
||||
},
|
||||
"revision_number": 22,
|
||||
"rollback": {
|
||||
"procedure_ref": "runbook:rollback-r22",
|
||||
"supported": true,
|
||||
"target_revision": "R-000220"
|
||||
},
|
||||
"schema_version": "0.1",
|
||||
"state": "CANDIDATE",
|
||||
"verification": {
|
||||
"policy_check": "PASSED",
|
||||
"security_check": "PASSED",
|
||||
"status": "PASSED",
|
||||
"test_refs": [
|
||||
"test:unit-12081",
|
||||
"test:contract-8821",
|
||||
"test:security-610",
|
||||
"test:compat-suite-775"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
25
conformance/fixtures/json/routing-policy.json
Normal file
25
conformance/fixtures/json/routing-policy.json
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
{
|
||||
"routing_policy": {
|
||||
"default_revision": "R-000220",
|
||||
"generation": 118,
|
||||
"id": "rp-118",
|
||||
"interface": "customer-finance-api",
|
||||
"issued_at": "2026-09-05T08:00:00Z",
|
||||
"issued_by": {
|
||||
"id": "fluid-experiment-controller",
|
||||
"type": "system"
|
||||
},
|
||||
"rules": [
|
||||
{
|
||||
"allocation": {
|
||||
"R-000220": 0.8,
|
||||
"R-000221": 0.2
|
||||
},
|
||||
"cohort": "coding-agents",
|
||||
"experiment": "E-000093",
|
||||
"sticky_by": "consumer_id"
|
||||
}
|
||||
],
|
||||
"schema_version": "0.1"
|
||||
}
|
||||
}
|
||||
34
conformance/fixtures/json/telemetry-envelope.json
Normal file
34
conformance/fixtures/json/telemetry-envelope.json
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
{
|
||||
"fluid_telemetry": {
|
||||
"cohort": "coding-agents",
|
||||
"consumer_ref": "psu-4d1e9c",
|
||||
"correlation_id": "c-7f21ab90",
|
||||
"experiment": "E-000093",
|
||||
"id": "tl-01J8Z3XK7QW2",
|
||||
"interface_id": "customer-finance-api",
|
||||
"kind": "request",
|
||||
"occurred_at": "2026-09-05T08:14:22Z",
|
||||
"redaction": {
|
||||
"applied": true,
|
||||
"rules": [
|
||||
"drop-path-parameters",
|
||||
"pseudonymize-consumer"
|
||||
]
|
||||
},
|
||||
"request": {
|
||||
"latency_ms": 118.4,
|
||||
"method": "GET",
|
||||
"operation": "getLatestInvoice",
|
||||
"request_bytes": 0,
|
||||
"response_bytes": 812,
|
||||
"route": "/customers/{id}/invoices/latest",
|
||||
"status": 200
|
||||
},
|
||||
"resolution": {
|
||||
"policy_generation": 118,
|
||||
"reason": "experiment_assignment"
|
||||
},
|
||||
"revision": "R-000221",
|
||||
"schema_version": "0.1"
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue