@fourier-labs/harbour-contracts 0.4.0 → 0.5.0

package/schema/ai-policy-snapshot.schema.json

@@ -0,0 +1,340 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-policy-snapshot.schema.json",
+  "title": "AiPolicySnapshot",
+  "description": "Immutable, content-addressed AI policy snapshot consumed by the Harbour AI Gateway. Provider credentials are represented only by Secrets Manager references.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "scope",
+    "revision",
+    "publishedAt",
+    "contentDigest",
+    "baselineDigest",
+    "providers",
+    "models",
+    "routes",
+    "policies",
+    "limits",
+    "retention"
+  ],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-policy-snapshot/1.0" },
+    "scope": { "$ref": "#/definitions/AiPolicyScope" },
+    "revision": { "type": "integer", "minimum": 1 },
+    "publishedAt": { "type": "string", "format": "date-time" },
+    "contentDigest": { "$ref": "#/definitions/AiPolicyDigest" },
+    "baselineDigest": { "$ref": "#/definitions/AiPolicyDigest" },
+    "classificationMinimum": { "$ref": "#/definitions/AiPolicyClassificationMinimum" },
+    "providers": {
+      "type": "array",
+      "maxItems": 64,
+      "items": { "$ref": "#/definitions/AiPolicyProvider" }
+    },
+    "models": {
+      "type": "array",
+      "maxItems": 512,
+      "items": { "$ref": "#/definitions/AiPolicyModel" }
+    },
+    "routes": {
+      "type": "array",
+      "maxItems": 256,
+      "items": { "$ref": "#/definitions/AiPolicyRoute" }
+    },
+    "policies": {
+      "type": "array",
+      "maxItems": 256,
+      "items": { "$ref": "#/definitions/AiPolicyRuleSet" }
+    },
+    "limits": {
+      "type": "array",
+      "maxItems": 128,
+      "items": { "$ref": "#/definitions/AiPolicyLimit" }
+    },
+    "retention": { "$ref": "#/definitions/AiPolicyRetention" }
+  },
+  "definitions": {
+    "AiPolicyIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$"
+    },
+    "AiPolicyDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "AiPolicyScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "tenantId"],
+      "properties": {
+        "level": { "type": "string", "enum": ["tenant", "application_environment"] },
+        "tenantId": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "appId": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "environment": { "$ref": "#/definitions/AiPolicyIdentifier" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "level": { "const": "application_environment" } } },
+          "then": { "required": ["appId", "environment"] }
+        },
+        {
+          "if": { "properties": { "level": { "const": "tenant" } } },
+          "then": {
+            "not": {
+              "anyOf": [
+                { "required": ["appId"] },
+                { "required": ["environment"] }
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "AiPolicyClassificationMinimum": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["classification", "mappingDigest"],
+      "properties": {
+        "classification": { "type": "string", "enum": ["Green", "Yellow", "Orange", "Red"] },
+        "mappingDigest": { "$ref": "#/definitions/AiPolicyDigest" }
+      }
+    },
+    "AiPolicyProvider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "provider", "credentialSecretRef", "enabled"],
+      "properties": {
+        "id": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini", "openrouter"] },
+        "baseUrl": { "type": "string", "format": "uri", "maxLength": 512 },
+        "credentialSecretRef": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^aws-sm://[A-Za-z0-9/_+=.@-]+$"
+        },
+        "enabled": { "type": "boolean" }
+      }
+    },
+    "AiPolicyPricing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["revision", "inputMicroUsdPerMillion", "outputMicroUsdPerMillion"],
+      "properties": {
+        "revision": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "inputMicroUsdPerMillion": { "type": "integer", "minimum": 0 },
+        "outputMicroUsdPerMillion": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "AiPolicyModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "providerId", "providerModel", "capabilities", "approved", "pricing"],
+      "properties": {
+        "id": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "providerId": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "providerModel": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "capabilities": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "uniqueItems": true,
+          "items": { "type": "string", "enum": ["generation", "embeddings"] }
+        },
+        "approved": { "type": "boolean" },
+        "pricing": { "$ref": "#/definitions/AiPolicyPricing" }
+      }
+    },
+    "AiPolicyRouteTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelId", "priority", "weight"],
+      "properties": {
+        "modelId": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "priority": { "type": "integer", "minimum": 0 },
+        "weight": { "type": "integer", "minimum": 1, "maximum": 10000 }
+      }
+    },
+    "AiPolicyRoute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["alias", "version", "capability", "targets", "retryCount", "timeoutMs"],
+      "properties": {
+        "alias": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "version": { "type": "integer", "minimum": 1 },
+        "capability": { "type": "string", "enum": ["generation", "embeddings"] },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": { "$ref": "#/definitions/AiPolicyRouteTarget" }
+        },
+        "retryCount": { "type": "integer", "minimum": 0, "maximum": 5 },
+        "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000 }
+      }
+    },
+    "AiPolicyGuardrailRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "detectorId", "detectorVersion", "phase", "action"],
+      "properties": {
+        "ruleId": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "detectorId": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "detectorVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "phase": { "type": "string", "enum": ["input", "output"] },
+        "action": { "type": "string", "enum": ["ALLOW", "OBSERVE", "REDACT", "BLOCK"] },
+        "parameters": { "$ref": "#/definitions/AiPolicyGuardrailParameters" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "detectorId": { "const": "output.json_schema" } },
+            "required": ["detectorId"]
+          },
+          "then": {
+            "required": ["parameters"],
+            "properties": {
+              "parameters": {
+                "oneOf": [
+                  { "required": ["jsonSchema"], "not": { "required": ["jsonSchemaRef"] } },
+                  { "required": ["jsonSchemaRef"], "not": { "required": ["jsonSchema"] } }
+                ]
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "parameters": {
+                "not": {
+                  "anyOf": [
+                    { "required": ["jsonSchema"] },
+                    { "required": ["jsonSchemaRef"] }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "AiPolicyGuardrailParameters": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowedTools": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }
+        },
+        "jsonSchema": { "$ref": "#/definitions/AiPolicyEmbeddedJsonSchema" },
+        "jsonSchemaRef": { "$ref": "#/definitions/AiPolicyDigest" }
+      }
+    },
+    "AiPolicyEmbeddedJsonSchema": {
+      "description": "Bounded, closed JSON Schema subset carried by an output.json_schema guardrail. Every node is a closed object over an enumerated keyword set; object nodes must state additionalProperties: false, so the validated output shape is closed too. Size is bounded per node (maxProperties/maxLength/maxItems); the consuming validator additionally enforces an overall byte budget at policy load.",
+      "type": "object",
+      "additionalProperties": false,
+      "maxProperties": 16,
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "enum": ["object", "array", "string", "number", "integer", "boolean", "null"] },
+        "description": { "type": "string", "maxLength": 512 },
+        "properties": {
+          "type": "object",
+          "maxProperties": 64,
+          "propertyNames": { "minLength": 1, "maxLength": 128 },
+          "additionalProperties": { "$ref": "#/definitions/AiPolicyEmbeddedJsonSchema" }
+        },
+        "required": {
+          "type": "array",
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 128 }
+        },
+        "additionalProperties": { "type": "boolean", "const": false },
+        "items": { "$ref": "#/definitions/AiPolicyEmbeddedJsonSchema" },
+        "enum": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": { "type": ["string", "number", "integer", "boolean", "null"] }
+        },
+        "minimum": { "type": "number" },
+        "maximum": { "type": "number" },
+        "minLength": { "type": "integer", "minimum": 0 },
+        "maxLength": { "type": "integer", "minimum": 0 },
+        "minItems": { "type": "integer", "minimum": 0 },
+        "maxItems": { "type": "integer", "minimum": 0 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "object" } } },
+          "then": { "required": ["additionalProperties"] }
+        }
+      ]
+    },
+    "AiPolicyPermittedRequestFields": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["temperature", "maxOutputTokens", "responseFormat", "tools"],
+      "properties": {
+        "temperature": { "type": "boolean" },
+        "maxOutputTokens": { "type": "boolean" },
+        "responseFormat": { "type": "boolean" },
+        "tools": { "type": "boolean" }
+      }
+    },
+    "AiPolicyRuleSet": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "maxRequestBytes", "maxInputTokens", "maxOutputTokens", "bufferedDelivery", "permittedRequestFields", "guardrails"],
+      "properties": {
+        "name": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "version": { "type": "integer", "minimum": 1 },
+        "maxRequestBytes": { "type": "integer", "minimum": 1 },
+        "maxInputTokens": { "type": "integer", "minimum": 1 },
+        "maxOutputTokens": { "type": "integer", "minimum": 1 },
+        "bufferedDelivery": { "type": "boolean" },
+        "permittedRequestFields": { "$ref": "#/definitions/AiPolicyPermittedRequestFields" },
+        "guardrails": {
+          "type": "array",
+          "maxItems": 128,
+          "items": { "$ref": "#/definitions/AiPolicyGuardrailRule" }
+        }
+      }
+    },
+    "AiPolicyLimit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "enabled", "scope", "requestsPerMinute", "tokensPerMinute", "monthlyBudgetMicroUsd"],
+      "properties": {
+        "name": { "$ref": "#/definitions/AiPolicyIdentifier" },
+        "enabled": { "type": "boolean" },
+        "scope": { "type": "string", "enum": ["tenant", "application"] },
+        "requestsPerMinute": { "type": "integer", "minimum": 1 },
+        "tokensPerMinute": { "type": "integer", "minimum": 1 },
+        "monthlyBudgetMicroUsd": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "AiPolicyRetention": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["captureMode", "retentionDays", "revealRoles"],
+      "properties": {
+        "captureMode": { "type": "string", "enum": ["OFF", "BEST_EFFORT", "REQUIRED"] },
+        "retentionDays": { "type": "integer", "minimum": 1, "maximum": 90 },
+        "revealRoles": {
+          "type": "array",
+          "maxItems": 16,
+          "uniqueItems": true,
+          "items": { "$ref": "#/definitions/AiPolicyIdentifier" }
+        }
+      }
+    }
+  }
+}

package/schema/ai-runtime-contract.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-runtime-contract.schema.json",
+  "title": "AiRuntimeContract",
+  "description": "Immutable deployment runtime contract derived by an AI Governance PLAN decision. Contains only scoped configuration and a Secrets Manager reference, never key plaintext.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "tenantId",
+    "appId",
+    "environment",
+    "versionId",
+    "sourceRevision",
+    "mode",
+    "gatewayBaseUrl",
+    "gatewayKeySecretRef",
+    "modelAliases",
+    "policyDigest",
+    "requiredStrategies"
+  ],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-runtime-contract/1.0" },
+    "tenantId": { "$ref": "#/definitions/AiRuntimeIdentifier" },
+    "appId": { "$ref": "#/definitions/AiRuntimeIdentifier" },
+    "environment": { "$ref": "#/definitions/AiRuntimeIdentifier" },
+    "versionId": {
+      "type": "string",
+      "minLength": 7,
+      "maxLength": 320,
+      "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$"
+    },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "mode": { "type": "string", "enum": ["observe", "enforce"] },
+    "gatewayBaseUrl": {
+      "type": "string",
+      "format": "uri",
+      "maxLength": 512,
+      "pattern": "^https://[^?#]+/v1$"
+    },
+    "gatewayKeySecretRef": {
+      "type": "string",
+      "maxLength": 512,
+      "pattern": "^aws-sm://[A-Za-z0-9/_+=.@-]+$"
+    },
+    "modelAliases": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "generation": { "$ref": "#/definitions/AiRuntimeModelAlias" },
+        "embeddings": { "$ref": "#/definitions/AiRuntimeModelAlias" }
+      }
+    },
+    "policyDigest": { "$ref": "#/definitions/AiRuntimeDigest" },
+    "requiredStrategies": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 2,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["deployment_injection", "deterministic_adapter"]
+      }
+    }
+  },
+  "definitions": {
+    "AiRuntimeIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+    },
+    "AiRuntimeDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "AiRuntimeModelAlias": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 160,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_./-]*$"
+    }
+  }
+}

package/schema/ai-trace-event.schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-trace-event.schema.json",
+  "title": "AiTraceEvent",
+  "description": "Value-free asynchronous AI Gateway trace metadata. Raw prompts and responses never enter the queue; captured content is referenced only after successful encrypted storage.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "traceId",
+    "requestId",
+    "tenantId",
+    "appId",
+    "environment",
+    "versionId",
+    "policyDigest",
+    "outcome",
+    "costMicroUsd",
+    "latencyMs",
+    "retryCount",
+    "fallbackUsed",
+    "attempts",
+    "guardrailResults",
+    "contentCaptureStatus",
+    "occurredAt"
+  ],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-trace-event/1.0" },
+    "traceId": { "type": "string", "pattern": "^trc_[A-Za-z0-9_-]+$", "maxLength": 160 },
+    "requestId": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$", "maxLength": 160 },
+    "tenantId": { "$ref": "#/definitions/AiTraceIdentifier" },
+    "appId": { "$ref": "#/definitions/AiTraceIdentifier" },
+    "environment": { "$ref": "#/definitions/AiTraceIdentifier" },
+    "versionId": {
+      "type": "string",
+      "minLength": 7,
+      "maxLength": 320,
+      "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$"
+    },
+    "callsiteFingerprint": { "$ref": "#/definitions/AiTraceDigest" },
+    "policyDigest": { "$ref": "#/definitions/AiTraceDigest" },
+    "routeRevision": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "requestedModel": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "governedModelAlias": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini", "openrouter"] },
+    "providerModel": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "outcome": { "type": "string", "enum": ["succeeded", "blocked", "failed", "cancelled"] },
+    "usage": { "$ref": "#/definitions/AiTraceUsage" },
+    "priceRevision": { "$ref": "#/definitions/AiTraceIdentifier" },
+    "costMicroUsd": { "type": "integer", "minimum": 0 },
+    "latencyMs": { "type": "integer", "minimum": 0 },
+    "retryCount": { "type": "integer", "minimum": 0, "maximum": 32 },
+    "fallbackUsed": { "type": "boolean" },
+    "reservationId": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "attempts": {
+      "type": "array",
+      "minItems": 0,
+      "maxItems": 32,
+      "items": { "$ref": "#/definitions/AiTraceAttempt" }
+    },
+    "guardrailResults": {
+      "type": "array",
+      "maxItems": 128,
+      "items": { "$ref": "#/definitions/AiTraceGuardrailResult" }
+    },
+    "contentCaptureStatus": {
+      "type": "string",
+      "enum": ["off", "captured", "capture_failed"]
+    },
+    "contentRef": {
+      "type": "string",
+      "maxLength": 1024,
+      "pattern": "^s3://[^/]+/.+$"
+    },
+    "retentionExpiresAt": { "type": "string", "format": "date-time" },
+    "occurredAt": { "type": "string", "format": "date-time" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "contentCaptureStatus": { "const": "captured" } } },
+      "then": { "required": ["contentRef", "retentionExpiresAt"] },
+      "else": {
+        "not": {
+          "anyOf": [
+            { "required": ["contentRef"] },
+            { "required": ["retentionExpiresAt"] }
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "attempts": { "minItems": 1 } },
+        "required": ["attempts"]
+      },
+      "then": {
+        "required": ["routeRevision", "provider", "providerModel", "priceRevision"]
+      }
+    },
+    {
+      "if": {
+        "properties": { "outcome": { "const": "succeeded" } },
+        "required": ["outcome"]
+      },
+      "then": {
+        "required": ["requestedModel", "governedModelAlias", "reservationId", "usage"],
+        "properties": { "attempts": { "minItems": 1 } }
+      }
+    }
+  ],
+  "definitions": {
+    "AiTraceIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+    },
+    "AiTraceDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "AiTraceUsage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inputTokens", "outputTokens"],
+      "properties": {
+        "inputTokens": { "type": "integer", "minimum": 0 },
+        "outputTokens": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "AiTraceAttempt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["attempt", "provider", "providerModel", "priceRevision", "outcome", "usage", "costMicroUsd", "latencyMs"],
+      "properties": {
+        "attempt": { "type": "integer", "minimum": 1, "maximum": 32 },
+        "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini", "openrouter"] },
+        "providerModel": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "priceRevision": { "$ref": "#/definitions/AiTraceIdentifier" },
+        "outcome": { "type": "string", "enum": ["succeeded", "failed", "timed_out", "cancelled"] },
+        "usage": {
+          "description": "Provider-reported token usage, or null when the attempt did not succeed and the provider reported none. Null states that usage is UNKNOWN — estimates are never fabricated. A succeeded attempt always reports real usage.",
+          "oneOf": [
+            { "$ref": "#/definitions/AiTraceUsage" },
+            { "type": "null" }
+          ]
+        },
+        "costMicroUsd": { "type": "integer", "minimum": 0 },
+        "latencyMs": { "type": "integer", "minimum": 0 },
+        "errorCode": { "type": "string", "minLength": 1, "maxLength": 160 }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "outcome": { "const": "succeeded" } },
+            "required": ["outcome"]
+          },
+          "then": {
+            "properties": { "usage": { "$ref": "#/definitions/AiTraceUsage" } }
+          }
+        }
+      ]
+    },
+    "AiTraceGuardrailResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "detectorId", "detectorVersion", "phase", "action", "result"],
+      "properties": {
+        "ruleId": { "type": "string", "minLength": 1, "maxLength": 160 },
+        "detectorId": { "type": "string", "minLength": 1, "maxLength": 160 },
+        "detectorVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "phase": { "type": "string", "enum": ["input", "output"] },
+        "action": { "type": "string", "enum": ["ALLOW", "OBSERVE", "REDACT", "BLOCK"] },
+        "result": { "type": "string", "enum": ["passed", "matched", "blocked", "redacted"] }
+      }
+    }
+  }
+}