coulomb/fluid-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add FLUID wire contract schemas

Browse source 
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:
tegwick 2026-09-04 01:55:47 +02:00
parent 7d2fc2af5d
commit fbbf56df7a
11 changed files with 1242 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

161
schemas/common.schema.json Normal file
View file

@ -0,0 +1,161 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://fluid.dev/schemas/common.schema.json",
"title": "FLUID common definitions",
"description": "Shared identifier, reference and measurement types. Identifier prefixes follow FluidHypothesisRevisionSchema.md section 16.",
"$defs": {
"schemaVersion": {
"type": "string",
"const": "0.1"
},
"interfaceId": {
"type": "string",
"minLength": 1,
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
"description": "Stable identifier of the owning interface."
},
"hypothesisId": { "type": "string", "pattern": "^H-[0-9A-Za-z_-]+$" },
"revisionId": { "type": "string", "pattern": "^R-[0-9A-Za-z_-]+$" },
"experimentId": { "type": "string", "pattern": "^E-[0-9A-Za-z_-]+$" },
"pressureId": { "type": "string", "pattern": "^P-[0-9A-Za-z_-]+$" },
"backendRequirementId": { "type": "string", "pattern": "^BR-[0-9A-Za-z_-]+$" },
"decisionId": { "type": "string", "pattern": "^D-[0-9A-Za-z_-]+$" },
"eventId": { "type": "string", "pattern": "^EV-[0-9A-Za-z_-]+$" },
"feedbackId": { "type": "string", "pattern": "^F-[0-9A-Za-z_-]+$" },
"cohortId": { "type": "string", "minLength": 1 },
"timestamp": { "type": "string", "format": "date-time" },
"evidenceRef": {
"type": "string",
"minLength": 1,
"description": "Opaque reference into the evidence store, conventionally '<kind>:<locator>' such as 'telemetry:invoice-pattern-2026w36'."
},
"artifactRef": {
"type": "string",
"minLength": 1,
"description": "Opaque reference into the artifact store."
},
"digest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Content address of an artifact."
},
"actor": {
"type": "object",
"description": "Who or what performed an action. FLUID distinguishes these because trust levels differ (ArchitectureBlueprint.md section 47).",
"properties": {
"type": { "enum": ["human", "daimon", "policy", "system", "consumer"] },
"id": { "type": "string", "minLength": 1 },
"model_or_agent": { "type": "string" }
},
"required": ["type", "id"],
"additionalProperties": false
},
"observationWindow": {
"type": "object",
"properties": {
"start": { "$ref": "common.schema.json#/$defs/timestamp" },
"end": {
"oneOf": [
{ "$ref": "common.schema.json#/$defs/timestamp" },
{ "type": "null" }
],
"description": "Null while the window is still open."
}
},
"required": ["start"],
"additionalProperties": false
},
"unitInterval": { "type": "number", "minimum": 0, "maximum": 1 },
"pressureClass": {
"enum": [
"natural_usage",
"successful_but_inefficient_usage",
"recoverable_misunderstanding",
"repeated_expectation_mismatch",
"poor_discoverability",
"missing_interface_capability",
"missing_backend_capability",
"out_of_scope_demand",
"prohibited_demand",
"implementation_failure"
],
"description": "FluidAPIStandards.md section 13."
},
"adaptationClass": {
"enum": ["presentation", "contract", "composition", "implementation", "requirement_escalation"],
"description": "FluidAPIStandards.md section 16."
},
"guardrail": {
"type": "object",
"description": "A constraint that must not regress beyond threshold. Guardrails are evaluated deterministically.",
"properties": {
"metric": { "type": "string", "minLength": 1 },
"operator": { "enum": ["<", "<=", "==", "!=", ">=", ">"] },
"threshold": { "type": ["number", "boolean", "string"] }
},
"required": ["metric", "operator", "threshold"],
"additionalProperties": false
},
"expectedOutcome": {
"type": "object",
"properties": {
"metric": { "type": "string", "minLength": 1 },
"cohort": { "type": "string" },
"baseline": { "type": "number" },
"target": { "type": "number" },
"direction": { "enum": ["lower", "higher", "unchanged"] }
},
"required": ["metric", "target", "direction"],
"additionalProperties": false
},
"complexityDelta": {
"type": "object",
"description": "Standard dimensions, implementation-defined scoring (FluidAPIStandards.md section 22).",
"properties": {
"surface_area": { "type": "number" },
"concept_count": { "type": "number" },
"operation_count": { "type": "number" },
"parameter_dimensionality": { "type": "number" },
"semantic_overlap": { "type": "number" },
"alternative_path_count": { "type": "number" },
"dependency_count": { "type": "number" },
"backend_composition_count": { "type": "number" },
"exception_count": { "type": "number" },
"active_revision_count": { "type": "number" },
"cognitive_load": { "type": "number" }
},
"additionalProperties": false
},
"fitnessDimensions": {
"type": "object",
"description": "FluidAPIStandards.md section 20. No universal scalar is defined on purpose.",
"properties": {
"client_utility": { "type": "number" },
"correctness": { "type": "number" },
"reliability": { "type": "number" },
"availability": { "type": "number" },
"performance": { "type": "number" },
"discoverability": { "type": "number" },
"simplicity": { "type": "number" },
"compatibility": { "type": "number" },
"security": { "type": "number" },
"maintainability": { "type": "number" },
"operational_cost": { "type": "number" },
"implementation_cost": { "type": "number" },
"resource_consumption": { "type": "number" }
},
"additionalProperties": false
}
}
}