Add FLUID wire contract schemas
Nine JSON Schemas covering the five record types from the schema spec, plus backend requirements, feedback, the revision descriptor, routing policy and the telemetry envelope. These are the integration boundary: readable without any fluid-core code, so adapters may be written in any language. 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
7d2fc2af5d
commit
fbbf56df7a
11 changed files with 1242 additions and 0 deletions
228
schemas/hypothesis.schema.json
Normal file
228
schemas/hypothesis.schema.json
Normal file
|
|
@ -0,0 +1,228 @@
|
|||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://fluid.dev/schemas/hypothesis.schema.json",
|
||||
"title": "FLUID hypothesis record",
|
||||
"description": "Why an interface change should be explored. Observation, explanation, prediction, intervention and result stay separate on purpose (FluidHypothesisRevisionSchema.md section 18).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"fluid_hypothesis": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"schema_version": { "$ref": "common.schema.json#/$defs/schemaVersion" },
|
||||
"id": { "$ref": "common.schema.json#/$defs/hypothesisId" },
|
||||
"interface_id": { "$ref": "common.schema.json#/$defs/interfaceId" },
|
||||
"state": {
|
||||
"enum": ["DRAFT", "READY", "PRIORITIZED", "DESIGNING", "EXPERIMENTING", "EVALUATING", "ACCEPTED", "REJECTED", "SUPERSEDED", "DEFERRED"]
|
||||
},
|
||||
"created_at": { "$ref": "common.schema.json#/$defs/timestamp" },
|
||||
"created_by": { "$ref": "common.schema.json#/$defs/actor" },
|
||||
"title": { "type": "string", "minLength": 1 },
|
||||
|
||||
"observation": {
|
||||
"type": "object",
|
||||
"description": "What was seen. Not what it means.",
|
||||
"properties": {
|
||||
"summary": { "type": "string", "minLength": 1 },
|
||||
"evidence_refs": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "common.schema.json#/$defs/evidenceRef" },
|
||||
"minItems": 1
|
||||
},
|
||||
"affected_cohorts": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/cohortId" } },
|
||||
"observation_window": { "$ref": "common.schema.json#/$defs/observationWindow" }
|
||||
},
|
||||
"required": ["summary", "evidence_refs"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"pressure": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"classes": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/pressureClass" }, "minItems": 1 },
|
||||
"pressure_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/pressureId" } },
|
||||
"severity": { "$ref": "common.schema.json#/$defs/unitInterval" },
|
||||
"confidence": { "$ref": "common.schema.json#/$defs/unitInterval" }
|
||||
},
|
||||
"required": ["classes"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"explanation": {
|
||||
"type": "object",
|
||||
"description": "What we think explains the observation.",
|
||||
"properties": {
|
||||
"claim": { "type": "string", "minLength": 1 },
|
||||
"reach": {
|
||||
"type": "object",
|
||||
"description": "Explanatory reach is a prioritization signal, never a correctness claim (FluidAPIStandards.md section 18).",
|
||||
"properties": {
|
||||
"score": { "type": "number" },
|
||||
"explains": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/pressureId" } },
|
||||
"notes": { "type": "string" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": ["claim"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"proposed_adaptation": {
|
||||
"type": "object",
|
||||
"description": "What we propose to change.",
|
||||
"properties": {
|
||||
"class": { "$ref": "common.schema.json#/$defs/adaptationClass" },
|
||||
"summary": { "type": "string", "minLength": 1 },
|
||||
"candidate_contract": {
|
||||
"type": "object",
|
||||
"description": "Shape is protocol-specific and deliberately unconstrained.",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"implementation_scope": { "enum": ["interface_only", "interface_and_backend", "documentation_only"] }
|
||||
},
|
||||
"required": ["class", "summary"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"backend_requirements": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"required": { "type": "boolean" },
|
||||
"requirement_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/backendRequirementId" } }
|
||||
},
|
||||
"required": ["required"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"expected_outcomes": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "common.schema.json#/$defs/expectedOutcome" },
|
||||
"minItems": 1,
|
||||
"description": "A hypothesis must be falsifiable (FluidAPIStandards.md section 17)."
|
||||
},
|
||||
"guardrails": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "common.schema.json#/$defs/guardrail" }
|
||||
},
|
||||
|
||||
"fitness_dimensions": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"expected": { "$ref": "common.schema.json#/$defs/fitnessDimensions" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"complexity": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"expected_delta": { "$ref": "common.schema.json#/$defs/complexityDelta" },
|
||||
"score": { "type": "number" }
|
||||
},
|
||||
"required": ["expected_delta"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"risk": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"level": { "enum": ["LOW", "MEDIUM", "HIGH", "CRITICAL"] },
|
||||
"reasons": { "type": "array", "items": { "type": "string" } }
|
||||
},
|
||||
"required": ["level"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"economics": {
|
||||
"type": "object",
|
||||
"description": "A hypothesis may be valuable but not yet worth exploring (ArchitectureBlueprint.md section 29).",
|
||||
"properties": {
|
||||
"estimated_experiment_cost": { "type": "number", "minimum": 0 },
|
||||
"estimated_implementation_cost": { "type": "number", "minimum": 0 },
|
||||
"currency": { "type": "string" },
|
||||
"expected_value_class": { "enum": ["LOW", "MEDIUM", "HIGH"] }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"learning_value": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"score": { "type": "number" },
|
||||
"notes": { "type": "string" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"priority": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"score": { "type": "number" },
|
||||
"decided_by": { "type": "string" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"competition": {
|
||||
"type": "object",
|
||||
"description": "Competing hypotheses are legitimate (FluidAPIStandards.md section 19).",
|
||||
"properties": {
|
||||
"group_id": { "type": "string", "minLength": 1 },
|
||||
"alternatives": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/hypothesisId" } }
|
||||
},
|
||||
"required": ["group_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"success_criteria": {
|
||||
"type": "object",
|
||||
"properties": { "expression": { "type": "string", "minLength": 1 } },
|
||||
"required": ["expression"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"failure_criteria": {
|
||||
"type": "object",
|
||||
"properties": { "expression": { "type": "string", "minLength": 1 } },
|
||||
"required": ["expression"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"candidate_revision_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/revisionId" } },
|
||||
"experiment_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/experimentId" } },
|
||||
|
||||
"outcome": {
|
||||
"type": "object",
|
||||
"description": "What happened afterwards. Null until evaluation completes.",
|
||||
"properties": {
|
||||
"status": {
|
||||
"oneOf": [
|
||||
{ "enum": ["CONFIRMED", "REFUTED", "INCONCLUSIVE"] },
|
||||
{ "type": "null" }
|
||||
]
|
||||
},
|
||||
"summary": { "type": ["string", "null"] },
|
||||
"evidence_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/evidenceRef" } }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
|
||||
"audit": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"decision_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/decisionId" } },
|
||||
"immutable_event_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/eventId" } }
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"schema_version", "id", "interface_id", "state", "title",
|
||||
"observation", "pressure", "explanation", "proposed_adaptation",
|
||||
"expected_outcomes", "guardrails", "complexity", "risk", "success_criteria"
|
||||
],
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": ["fluid_hypothesis"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue