@agent-teams/engineering-foundation 0.7.0 → 0.8.0

package/schemas/contract-protobuf-breaking-qualification/v2.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.agent-teams.ai/engineering-foundation/contract-protobuf-breaking-qualification/v2",
+  "title": "Hardened Buf FILE breaking qualification evidence",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "producerId",
+    "producerVersion",
+    "policy",
+    "contractId",
+    "bufVersion",
+    "modulePath",
+    "bufConfigPath",
+    "evidencePath",
+    "bufConfigDigest",
+    "baselineDescriptorImagePath",
+    "baselineDescriptorImageDigest",
+    "candidateDescriptorImageDigest",
+    "breakingPolicyConfigDigest",
+    "invocationDigest",
+    "result",
+    "evidenceDigest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "producerId": { "const": "agent-teams-foundation.buf-breaking-qualification" },
+    "producerVersion": { "const": 2 },
+    "policy": { "const": "FILE" },
+    "contractId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{1,119}$" },
+    "bufVersion": { "type": "string", "minLength": 1, "maxLength": 80 },
+    "modulePath": { "$ref": "#/$defs/repositoryPath" },
+    "bufConfigPath": { "$ref": "#/$defs/repositoryPath" },
+    "evidencePath": { "$ref": "#/$defs/repositoryPath" },
+    "bufConfigDigest": { "$ref": "#/$defs/digest" },
+    "baselineDescriptorImagePath": { "$ref": "#/$defs/repositoryPath" },
+    "baselineDescriptorImageDigest": { "$ref": "#/$defs/digest" },
+    "candidateDescriptorImageDigest": { "$ref": "#/$defs/digest" },
+    "breakingPolicyConfigDigest": { "$ref": "#/$defs/digest" },
+    "invocationDigest": { "$ref": "#/$defs/digest" },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "findings", "findingSetDigest", "rawOutputDigest"],
+      "properties": {
+        "status": { "enum": ["compatible", "breaking"] },
+        "findings": {
+          "type": "array",
+          "maxItems": 10000,
+          "items": { "$ref": "#/$defs/finding" }
+        },
+        "findingSetDigest": { "$ref": "#/$defs/digest" },
+        "rawOutputDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "evidenceDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//)[^\\u0000]+$"
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "startLine",
+        "startColumn",
+        "endLine",
+        "endColumn",
+        "type",
+        "message"
+      ],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "startLine": { "type": "integer", "minimum": 1 },
+        "startColumn": { "type": "integer", "minimum": 1 },
+        "endLine": { "type": "integer", "minimum": 1 },
+        "endColumn": { "type": "integer", "minimum": 1 },
+        "type": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "message": { "type": "string", "minLength": 1, "maxLength": 4000 }
+      }
+    }
+  }
+}

package/schemas/contract-protobuf-evolution/v2.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.agent-teams.ai/engineering-foundation/contract-protobuf-evolution/v2",
+  "title": "Protobuf contract evolution with qualified Buf FILE evidence",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "releasedBaselinePath",
+    "approvedBreakingChanges",
+    "qualification",
+    "current"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "releasedBaselinePath": { "$ref": "#/$defs/releasedBaselinePath" },
+    "acceptedDecisionBaselinePath": { "$ref": "#/$defs/acceptedDecisionBaselinePath" },
+    "governanceConfigPath": { "$ref": "#/$defs/governanceConfigPath" },
+    "approvedBreakingChanges": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "$ref": "#/$defs/breakingApproval" }
+    },
+    "qualification": { "$ref": "#/$defs/qualification" },
+    "current": { "$ref": "#/$defs/current" }
+  },
+  "$defs": {
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "contractId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9.-]{1,119}$"
+    },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//)[^\\u0000]+$"
+    },
+    "releasedBaselinePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "^architecture/contracts/(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//)[^\\u0000]+\\.(?:json|ya?ml)$"
+    },
+    "acceptedDecisionBaselinePath": {
+      "const": "architecture/decisions/accepted-decisions.json"
+    },
+    "governanceConfigPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+\\.ya?ml$"
+    },
+    "breakingApproval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["decisionId", "fingerprint"],
+      "properties": {
+        "decisionId": { "type": "string", "pattern": "^ADR-[0-9]{4}$" },
+        "fingerprint": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "generator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 240 }
+      }
+    },
+    "qualification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "modulePath",
+        "bufConfigPath",
+        "releasedDescriptorImagePath",
+        "evidencePath"
+      ],
+      "properties": {
+        "modulePath": { "$ref": "#/$defs/repositoryPath" },
+        "bufConfigPath": {
+          "allOf": [
+            { "$ref": "#/$defs/repositoryPath" },
+            { "type": "string", "pattern": "\\.ya?ml$" }
+          ]
+        },
+        "releasedDescriptorImagePath": {
+          "allOf": [
+            { "$ref": "#/$defs/repositoryPath" },
+            { "type": "string", "pattern": "^architecture/contracts/.+\\.binpb$" }
+          ]
+        },
+        "evidencePath": {
+          "allOf": [
+            { "$ref": "#/$defs/repositoryPath" },
+            { "type": "string", "pattern": "^architecture/evidence/protobuf/.+\\.json$" }
+          ]
+        }
+      }
+    },
+    "current": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "contractId",
+        "publicContractVersion",
+        "bufVersion",
+        "bufConfigDigest",
+        "descriptorImageDigest",
+        "generatorVersions",
+        "generationDrift"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 2 },
+        "contractId": { "$ref": "#/$defs/contractId" },
+        "publicContractVersion": { "$ref": "#/$defs/semver" },
+        "bufVersion": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "bufConfigDigest": { "$ref": "#/$defs/digest" },
+        "descriptorImageDigest": { "$ref": "#/$defs/digest" },
+        "generatorVersions": {
+          "type": "array",
+          "maxItems": 100,
+          "items": { "$ref": "#/$defs/generator" }
+        },
+        "generationDrift": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["expectedGeneratedOutputDigest", "observedGeneratedOutputDigest"],
+          "properties": {
+            "expectedGeneratedOutputDigest": { "$ref": "#/$defs/digest" },
+            "observedGeneratedOutputDigest": { "$ref": "#/$defs/digest" }
+          }
+        }
+      }
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)(?:-(?:(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"
+    }
+  }
+}

package/schemas/scaffold-authority-evidence.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/scaffold-authority-evidence",
+  "title": "Scaffold Authority Evidence",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "verifier", "projectId", "targetRef", "targetIdentityDigest", "ownerDocument", "sources", "evidenceDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "verifier": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "const": "foundation.markdown-yaml-owner" },
+        "contractVersion": { "const": 1 }
+      }
+    },
+    "projectId": { "$ref": "#/$defs/id" },
+    "targetRef": { "$ref": "#/$defs/id" },
+    "targetIdentityDigest": { "$ref": "#/$defs/digest" },
+    "ownerDocument": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "status"],
+      "properties": {
+        "id": { "$ref": "#/$defs/ownerDocumentId" },
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "status": { "$ref": "#/$defs/id" }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "prefixItems": [
+        { "$ref": "#/$defs/configSourceAssertion" },
+        { "$ref": "#/$defs/ownerSourceAssertion" },
+        { "$ref": "#/$defs/catalogSourceAssertion" }
+      ]
+    },
+    "evidenceDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[a-z0-9][a-z0-9._/-]*$"
+    },
+    "ownerDocumentId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]*$"
+    },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$"
+    },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "readAssertion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "state", "digest", "size"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "state": { "const": "file" },
+        "digest": { "$ref": "#/$defs/digest" },
+        "size": { "type": "integer", "minimum": 0, "maximum": 1048576 }
+      }
+    },
+    "sourceAssertion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "assertion"],
+      "properties": {
+        "role": { "enum": ["config", "target-catalog", "owner-document"] },
+        "assertion": { "$ref": "#/$defs/readAssertion" }
+      }
+    },
+    "configSourceAssertion": {
+      "allOf": [
+        { "$ref": "#/$defs/sourceAssertion" },
+        { "type": "object", "properties": { "role": { "const": "config" } }, "required": ["role"] }
+      ]
+    },
+    "ownerSourceAssertion": {
+      "allOf": [
+        { "$ref": "#/$defs/sourceAssertion" },
+        { "type": "object", "properties": { "role": { "const": "owner-document" } }, "required": ["role"] }
+      ]
+    },
+    "catalogSourceAssertion": {
+      "allOf": [
+        { "$ref": "#/$defs/sourceAssertion" },
+        { "type": "object", "properties": { "role": { "const": "target-catalog" } }, "required": ["role"] }
+      ]
+    }
+  }
+}

package/schemas/{scaffold-intent/v1.schema.json → scaffold-intent.schema.json}

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agent-teams.ai/schemas/scaffold-intent/v1",
-  "title": "Scaffold Intent v1",
+  "$id": "https://agent-teams.ai/schemas/scaffold-intent",
+  "title": "Scaffold Intent",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "compositionId", "targetRef"],

package/schemas/{scaffold-plan/v1.schema.json → scaffold-plan.schema.json}

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agent-teams.ai/schemas/scaffold-plan/v1",
-  "title": "Scaffold Plan v1",
+  "$id": "https://agent-teams.ai/schemas/scaffold-plan",
+  "title": "Scaffold Plan",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "protocolVersion", "compiler", "projectId", "authority", "intent", "intentDigest", "authoritySnapshotDigest", "composition", "definitions", "resolved", "target", "readSet", "requiredAdapterCapabilities", "operations", "diagnostics", "planDigest"],
+  "required": ["schemaVersion", "protocolVersion", "compiler", "projectId", "authority", "authorityEvidence", "intent", "intentDigest", "authoritySnapshotDigest", "composition", "definitions", "resolved", "target", "readSet", "requiredAdapterCapabilities", "operations", "diagnostics", "planDigest"],
   "properties": {
-    "schemaVersion": { "const": 1 },
-    "protocolVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
+    "protocolVersion": { "const": 2 },
     "compiler": {
       "type": "object",
       "additionalProperties": false,
@@ -27,6 +27,7 @@
         "targetCatalogPath": { "$ref": "#/$defs/repositoryPath" }
       }
     },
+    "authorityEvidence": { "$ref": "#/$defs/authorityEvidence" },
     "intent": { "$ref": "#/$defs/intent" },
     "intentDigest": { "$ref": "#/$defs/digest" },
     "authoritySnapshotDigest": { "$ref": "#/$defs/digest" },
@@ -77,7 +78,7 @@
       }
     },
     "target": { "$ref": "#/$defs/target" },
-    "readSet": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "$ref": "#/$defs/readAssertion" } },
+    "readSet": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "$ref": "#/$defs/readAssertion" } },
     "requiredAdapterCapabilities": {
       "type": "array",
       "prefixItems": [{ "const": "materialize-file/v1" }],
@@ -95,6 +96,12 @@
       "maxLength": 160,
       "pattern": "^[a-z0-9][a-z0-9._/-]*$"
     },
+    "ownerDocumentId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]*$"
+    },
     "artifactId": {
       "type": "string",
       "minLength": 1,
@@ -102,6 +109,74 @@
       "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/-]*$"
     },
     "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "authorityEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "verifier", "projectId", "targetRef", "targetIdentityDigest", "ownerDocument", "sources", "evidenceDigest"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "verifier": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "contractVersion"],
+          "properties": {
+            "id": { "const": "foundation.markdown-yaml-owner" },
+            "contractVersion": { "const": 1 }
+          }
+        },
+        "projectId": { "$ref": "#/$defs/authorityId" },
+        "targetRef": { "$ref": "#/$defs/authorityId" },
+        "targetIdentityDigest": { "$ref": "#/$defs/digest" },
+        "ownerDocument": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "path", "status"],
+          "properties": {
+            "id": { "$ref": "#/$defs/ownerDocumentId" },
+            "path": { "$ref": "#/$defs/repositoryPath" },
+            "status": { "$ref": "#/$defs/authorityId" }
+          }
+        },
+        "sources": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "prefixItems": [
+            { "$ref": "#/$defs/configAuthoritySourceAssertion" },
+            { "$ref": "#/$defs/ownerAuthoritySourceAssertion" },
+            { "$ref": "#/$defs/catalogAuthoritySourceAssertion" }
+          ]
+        },
+        "evidenceDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "authoritySourceAssertion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "assertion"],
+      "properties": {
+        "role": { "enum": ["config", "target-catalog", "owner-document"] },
+        "assertion": { "$ref": "#/$defs/readAssertion" }
+      }
+    },
+    "configAuthoritySourceAssertion": {
+      "allOf": [
+        { "$ref": "#/$defs/authoritySourceAssertion" },
+        { "type": "object", "properties": { "role": { "const": "config" } }, "required": ["role"] }
+      ]
+    },
+    "ownerAuthoritySourceAssertion": {
+      "allOf": [
+        { "$ref": "#/$defs/authoritySourceAssertion" },
+        { "type": "object", "properties": { "role": { "const": "owner-document" } }, "required": ["role"] }
+      ]
+    },
+    "catalogAuthoritySourceAssertion": {
+      "allOf": [
+        { "$ref": "#/$defs/authoritySourceAssertion" },
+        { "type": "object", "properties": { "role": { "const": "target-catalog" } }, "required": ["role"] }
+      ]
+    },
     "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$" },
     "definitionRef": {
       "type": "object",
@@ -174,7 +249,7 @@
     "target": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["id", "role", "path", "packageName"],
+      "required": ["id", "role", "path", "packageName", "ownerDocument"],
       "properties": {
         "id": { "$ref": "#/$defs/authorityId" },
         "role": { "$ref": "#/$defs/authorityId" },
@@ -186,10 +261,13 @@
           "pattern": "^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$"
         },
         "ownerDocument": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 512,
-          "pattern": "^[^\\u0000-\\u001F]+$"
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "path"],
+          "properties": {
+            "id": { "$ref": "#/$defs/ownerDocumentId" },
+            "path": { "$ref": "#/$defs/repositoryPath" }
+          }
         }
       }
     },