@evolith/core-domain 1.0.0 → 1.0.1

package/rulesets/schema/maturity-evidence.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/maturity-evidence.schema.json",
+  "title": "Maturity Evidence",
+  "description": "JSON Schema for validating maturity-evidence.json files in the Multi-Topology Reference Corpus.",
+  "type": "object",
+  "required": ["schemaVersion", "asOf", "checks"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Schema version version."
+    },
+    "asOf": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "Date of the maturity status snapshot."
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "observedAt", "commit", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["PASS", "BLOCKED", "RESOLVED"]
+          },
+          "observedAt": {
+            "type": "string",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+          },
+          "commit": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{7,40}$"
+          },
+          "source": {
+            "type": "string",
+            "format": "uri"
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "gap": {
+            "type": "string",
+            "pattern": "^(GT-\\d+|MT-A\\d+)$"
+          }
+        }
+      }
+    }
+  }
+}

package/rulesets/schema/observability-validation.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/observability-validation.schema.json",
+  "title": "Observability Validation",
+  "description": "JSON Schema for the Observability Validation artifact required by the Production Live gate (Phase 5). Records that metrics, logs, and traces are nominal for every production-bound path.",
+  "type": "object",
+  "required": ["release", "evaluatedAt", "metrics", "logs", "traces", "alerts", "result"],
+  "additionalProperties": false,
+  "properties": {
+    "release": {
+      "type": "string",
+      "description": "Release or RC identifier the validation belongs to."
+    },
+    "evaluatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "evaluator": {
+      "type": "string",
+      "description": "Owner (SRE/DevOps) who signed the validation."
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["errorRatePercent", "latencyP95Ms", "latencyP99Ms", "withinSlo"],
+      "additionalProperties": false,
+      "properties": {
+        "errorRatePercent": { "type": "number", "minimum": 0 },
+        "latencyP95Ms": { "type": "number", "minimum": 0 },
+        "latencyP99Ms": { "type": "number", "minimum": 0 },
+        "withinSlo": { "type": "boolean" },
+        "sloReference": { "type": "string", "description": "Link or identifier of the SLO baseline used to evaluate this release." }
+      }
+    },
+    "logs": {
+      "type": "object",
+      "required": ["errorVolume", "anomalies", "withinBaseline"],
+      "additionalProperties": false,
+      "properties": {
+        "errorVolume": { "type": "integer", "minimum": 0 },
+        "anomalies": { "type": "integer", "minimum": 0 },
+        "withinBaseline": { "type": "boolean" }
+      }
+    },
+    "traces": {
+      "type": "object",
+      "required": ["completeForCriticalPaths", "missingSpans"],
+      "additionalProperties": false,
+      "properties": {
+        "completeForCriticalPaths": { "type": "boolean" },
+        "missingSpans": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "alerts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "state", "owner"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "state": { "type": "string", "enum": ["nominal", "firing", "silenced"] },
+          "owner": { "type": "string" }
+        }
+      }
+    },
+    "result": {
+      "type": "string",
+      "enum": ["NOMINAL", "DEGRADED", "BLOCK"]
+    },
+    "waivers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["criterion", "justification", "owner", "expirationDate"],
+        "additionalProperties": false,
+        "properties": {
+          "criterion": { "type": "string" },
+          "justification": { "type": "string" },
+          "owner": { "type": "string" },
+          "expirationDate": { "type": "string", "format": "date" }
+        }
+      }
+    }
+  }
+}

package/rulesets/schema/on-call-handoff.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/on-call-handoff.schema.json",
+  "title": "On-Call Handoff Confirmation",
+  "description": "Structured evidence that the on-call team has been briefed and is ready to support a new production release.",
+  "type": "object",
+  "required": ["releaseVersion", "handoffDate", "runbookReferences", "escalationPaths", "alertOwnership", "slaAcknowledgement", "confirmation"],
+  "additionalProperties": false,
+  "properties": {
+    "releaseVersion": {
+      "type": "string",
+      "description": "Semantic version of the release being handed off."
+    },
+    "handoffDate": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO 8601 date when the handoff was confirmed."
+    },
+    "changeSummary": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Brief summary of what changed in this release."
+    },
+    "riskLevel": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "critical"],
+      "description": "Assessed risk level of the release."
+    },
+    "runbookReferences": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "url"],
+        "properties": {
+          "name": { "type": "string", "minLength": 3 },
+          "url": { "type": "string", "format": "uri" }
+        }
+      },
+      "description": "URLs to operational runbooks relevant to this release."
+    },
+    "escalationPaths": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["severity", "contact", "responseTimeMinutes"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["P1", "P2", "P3"] },
+          "contact": { "type": "string", "minLength": 2 },
+          "responseTimeMinutes": { "type": "integer", "minimum": 1 }
+        }
+      },
+      "description": "Escalation contacts per severity level."
+    },
+    "alertOwnership": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["alertName", "owner", "channel"],
+        "properties": {
+          "alertName": { "type": "string", "minLength": 3 },
+          "owner": { "type": "string", "minLength": 2 },
+          "channel": { "type": "string", "minLength": 2 }
+        }
+      },
+      "description": "Who monitors which alerts and through which channel."
+    },
+    "slaAcknowledgement": {
+      "type": "object",
+      "required": ["availability", "latencyP99Ms", "errorRatePercent"],
+      "properties": {
+        "availability": { "type": "string", "description": "e.g. 99.9%" },
+        "latencyP99Ms": { "type": "integer", "minimum": 1 },
+        "errorRatePercent": { "type": "number", "minimum": 0, "maximum": 100 }
+      },
+      "description": "SLO targets acknowledged by the on-call team."
+    },
+    "confirmation": {
+      "type": "object",
+      "required": ["onCallLead", "role", "date"],
+      "properties": {
+        "onCallLead": { "type": "string", "minLength": 2 },
+        "role": { "type": "string", "minLength": 2 },
+        "date": { "type": "string", "format": "date" }
+      },
+      "description": "On-call lead sign-off confirming readiness."
+    }
+  }
+}

package/rulesets/schema/output-envelope.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/output-envelope.schema.json",
+  "title": "Machine Output Envelope",
+  "description": "Universal envelope emitted by every machine-readable Evolith surface (CLI --format json, MCP tool results, REST), as ratified by core/ADR-0073. 'data' is success-only and schema-typed per operation (e.g. gate-evidence.schema.json); 'error' is failure-only.",
+  "type": "object",
+  "required": ["success", "meta"],
+  "additionalProperties": false,
+  "properties": {
+    "success": {
+      "type": "boolean",
+      "description": "Operation outcome discriminator. true requires 'data'; false requires 'error'."
+    },
+    "data": {
+      "description": "Operation result payload. Present only when success is true. Shape is operation-specific and schema-typed."
+    },
+    "error": {
+      "type": "object",
+      "required": ["code", "message"],
+      "additionalProperties": false,
+      "description": "Failure detail. Present only when success is false.",
+      "properties": {
+        "code": {
+          "type": "string",
+          "enum": [
+            "GATE_BLOCKED",
+            "VALIDATION_FAILED",
+            "RULESET_NOT_FOUND",
+            "SCHEMA_INVALID",
+            "INVALID_PHASE",
+            "NOT_A_SATELLITE",
+            "IO_ERROR",
+            "INTERNAL_ERROR"
+          ],
+          "description": "Registered machine-readable error code. The registry is append-only per core/ADR-0073."
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable failure explanation."
+        },
+        "details": {
+          "type": "object",
+          "description": "Optional structured failure context (violations, paths, hints)."
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["command", "executedAt", "durationMs", "correlationId", "schemaVersion"],
+      "additionalProperties": false,
+      "description": "Execution metadata present on every response.",
+      "properties": {
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Canonical command identity (e.g. 'evolith gate evaluate')."
+        },
+        "executedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of execution."
+        },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Wall-clock execution time in milliseconds."
+        },
+        "correlationId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Caller-supplied or generated correlation identifier for tracing."
+        },
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Semver pin of this envelope shape on the producing surface. Bumps MUST be reflected in surface-compatibility.json (GT-174)."
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Verbatim echo of caller-supplied context. The CLI never persists or interprets these values.",
+          "properties": {
+            "initiative": { "type": "string" },
+            "tenant": { "type": "string" },
+            "phase": { "type": "string" }
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "success": { "const": true } } },
+      "then": { "required": ["success", "data", "meta"], "not": { "required": ["error"] } }
+    },
+    {
+      "if": { "properties": { "success": { "const": false } } },
+      "then": { "required": ["success", "error", "meta"], "not": { "required": ["data"] } }
+    }
+  ]
+}

package/rulesets/schema/prd.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/prd.schema.json",
+  "title": "Product Requirements Document",
+  "description": "JSON Schema for validating Evolith PRD artifacts. Required in Phase 1 before design begins.",
+  "type": "object",
+  "required": ["title", "productOwner", "date", "scope", "goals", "personas", "constraints", "nonFunctionalRequirements"],
+  "additionalProperties": false,
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "PRD title clearly identifying the product or initiative."
+    },
+    "productOwner": {
+      "type": "string",
+      "description": "Name of the accountable Product Owner."
+    },
+    "date": {
+      "type": "string",
+      "format": "date",
+      "description": "Date when PRD was approved. ISO 8601 format."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Draft", "Under Review", "Approved", "Superseded"],
+      "default": "Draft"
+    },
+    "scope": {
+      "type": "object",
+      "required": ["inScope", "outOfScope"],
+      "additionalProperties": false,
+      "properties": {
+        "inScope": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "outOfScope": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "goals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["goal", "metric"],
+        "additionalProperties": false,
+        "properties": {
+          "goal": { "type": "string" },
+          "metric": { "type": "string" },
+          "targetDate": { "type": "string", "format": "date" }
+        }
+      },
+      "minItems": 1,
+      "description": "Business goals with measurable metrics."
+    },
+    "personas": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "role", "painPoints"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "role": { "type": "string" },
+          "painPoints": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      },
+      "minItems": 1,
+      "description": "Target user personas for this product."
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Technical, budget, timeline, and regulatory constraints."
+    },
+    "nonFunctionalRequirements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["requirement", "category", "threshold"],
+        "additionalProperties": false,
+        "properties": {
+          "requirement": { "type": "string" },
+          "category": {
+            "type": "string",
+            "enum": ["Performance", "Security", "Scalability", "Availability", "Compliance"]
+          },
+          "threshold": { "type": "string" }
+        }
+      },
+      "description": "NFRs with measurable thresholds."
+    },
+    "relatedADRs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "ADR IDs that constrain or enable this PRD."
+    },
+    "approvalEvidence": {
+      "type": "object",
+      "required": ["approver", "approvalDate"],
+      "additionalProperties": false,
+      "properties": {
+        "approver": { "type": "string" },
+        "approvalDate": { "type": "string", "format": "date" },
+        "meetingNotes": { "type": "string", "format": "uri" }
+      },
+      "description": "Evidence of business sign-off required for Phase 1 gate."
+    }
+  }
+}

package/rulesets/schema/release-notes.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/release-notes.schema.json",
+  "title": "Release Notes",
+  "description": "JSON Schema for validating Evolith Release Notes artifacts. Required for Production Live gate (Phase 5).",
+  "type": "object",
+  "required": ["version", "releaseCandidate", "date", "scope", "deployment", "rollback", "observability"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of this release."
+    },
+    "releaseCandidate": {
+      "type": "string",
+      "pattern": "^RC-\\d+\\.\\d+\\.\\d+$",
+      "description": "RC ID this release is based on."
+    },
+    "date": {
+      "type": "string",
+      "format": "date",
+      "description": "Deployment date. ISO 8601 format."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Draft", "Deployed", "Rolled Back"],
+      "default": "Draft"
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "newFeatures": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "breakingChanges": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "bugFixes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "improvements": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deployment": {
+      "type": "object",
+      "required": ["environment", "steps", "artifacts"],
+      "additionalProperties": false,
+      "properties": {
+        "environment": {
+          "type": "string",
+          "enum": ["Production", "Staging", "Canary"]
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["step", "command"],
+            "additionalProperties": false,
+            "properties": {
+              "step": { "type": "integer" },
+              "description": { "type": "string" },
+              "command": { "type": "string" },
+              "rollbackCommand": { "type": "string" }
+            }
+          },
+          "minItems": 1
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Docker images, DLLs, or artifacts deployed."
+        }
+      }
+    },
+    "rollback": {
+      "type": "object",
+      "required": ["procedure", "decisionCriteria"],
+      "additionalProperties": false,
+      "properties": {
+        "procedure": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "decisionCriteria": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Conditions under which rollback must be initiated."
+        },
+        "lastGoodVersion": { "type": "string" }
+      }
+    },
+    "observability": {
+      "type": "object",
+      "required": ["dashboards", "alerts", "healthEndpoint"],
+      "additionalProperties": false,
+      "properties": {
+        "dashboards": {
+          "type": "array",
+          "items": { "type": "string", "format": "uri" }
+        },
+        "alerts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Alert names or IDs activated for this release."
+        },
+        "healthEndpoint": { "type": "string" },
+        "metricsValidation": {
+          "type": "boolean",
+          "description": "Whether metrics were verified nominal before sign-off."
+        }
+      }
+    },
+    "testSummaryRef": {
+      "type": "string",
+      "description": "Reference to Test Summary Report that validated this RC."
+    },
+    "signOff": {
+      "type": "object",
+      "required": ["devOpsLead", "techLead", "date"],
+      "additionalProperties": false,
+      "properties": {
+        "devOpsLead": { "type": "string" },
+        "techLead": { "type": "string" },
+        "productOwner": { "type": "string" },
+        "date": { "type": "string", "format": "date" }
+      }
+    }
+  }
+}

package/rulesets/schema/rollback-rehearsal.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://evolith.dev/schema/rollback-rehearsal.schema.json",
+  "title": "Rollback Rehearsal Evidence",
+  "description": "Structured evidence that a rollback rehearsal was executed and confirmed working for a specific release.",
+  "type": "object",
+  "required": ["releaseVersion", "environment", "strategy", "rehearsalDate", "steps", "maxRollbackTimeMinutes", "actualRollbackTimeMinutes", "witness"],
+  "additionalProperties": false,
+  "properties": {
+    "releaseVersion": {
+      "type": "string",
+      "description": "Semantic version of the release being deployed."
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["staging", "pre-production", "production"],
+      "description": "Environment where the rollback rehearsal was executed."
+    },
+    "strategy": {
+      "type": "string",
+      "enum": ["blue-green", "canary", "rolling", "recreate"],
+      "description": "Deployment strategy used for the release."
+    },
+    "rehearsalDate": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO 8601 date when the rehearsal was performed."
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["order", "description", "completed"],
+        "properties": {
+          "order": { "type": "integer", "minimum": 1 },
+          "description": { "type": "string", "minLength": 5 },
+          "completed": { "type": "boolean" }
+        }
+      },
+      "description": "Numbered rollback steps executed during the rehearsal."
+    },
+    "maxRollbackTimeMinutes": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Maximum allowed rollback time in minutes (rollback budget)."
+    },
+    "actualRollbackTimeMinutes": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Actual time taken to complete the rollback in minutes."
+    },
+    "withinBudget": {
+      "type": "boolean",
+      "description": "Whether actual rollback time was within the budget."
+    },
+    "witness": {
+      "type": "object",
+      "required": ["name", "role", "date"],
+      "properties": {
+        "name": { "type": "string", "minLength": 2 },
+        "role": { "type": "string", "minLength": 2 },
+        "date": { "type": "string", "format": "date" }
+      },
+      "description": "Person who witnessed and confirmed the rehearsal."
+    },
+    "evidenceLinks": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri" },
+      "description": "URLs to logs, metrics dashboards, or screenshots supporting the rehearsal."
+    }
+  }
+}