@agent-teams/engineering-foundation 0.4.1 → 0.6.0

package/schemas/scaffold-plan/v1.schema.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/scaffold-plan/v1",
+  "title": "Scaffold Plan v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocolVersion", "compiler", "projectId", "authority", "intent", "intentDigest", "authoritySnapshotDigest", "composition", "definitions", "resolved", "target", "readSet", "requiredAdapterCapabilities", "operations", "diagnostics", "planDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "compiler": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "const": "@agent-teams/engineering-foundation" },
+        "version": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$" }
+      }
+    },
+    "projectId": { "$ref": "#/$defs/authorityId" },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["configPath", "targetCatalogPath"],
+      "properties": {
+        "configPath": { "$ref": "#/$defs/repositoryPath" },
+        "targetCatalogPath": { "$ref": "#/$defs/repositoryPath" }
+      }
+    },
+    "intent": { "$ref": "#/$defs/intent" },
+    "intentDigest": { "$ref": "#/$defs/digest" },
+    "authoritySnapshotDigest": { "$ref": "#/$defs/digest" },
+    "composition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "scaffoldProfile", "recipe", "facets", "policies"],
+      "properties": {
+        "id": { "$ref": "#/$defs/authorityId" },
+        "scaffoldProfile": { "$ref": "#/$defs/definitionRef" },
+        "recipe": { "$ref": "#/$defs/definitionRef" },
+        "facets": { "type": "array", "maxItems": 32, "items": { "$ref": "#/$defs/definitionRef" } },
+        "policies": { "type": "array", "maxItems": 32, "items": { "$ref": "#/$defs/definitionRef" } }
+      }
+    },
+    "definitions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 128,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "ref", "contractDigest"],
+        "properties": {
+          "kind": { "enum": ["facet", "policy", "recipe", "scaffold-profile"] },
+          "ref": { "$ref": "#/$defs/definitionRef" },
+          "contractDigest": { "$ref": "#/$defs/digest" }
+        }
+      }
+    },
+    "resolved": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["profileParameters", "recipeParameters", "facets", "policies"],
+      "properties": {
+        "profileParameters": { "$ref": "#/$defs/jsonObject" },
+        "recipeParameters": { "$ref": "#/$defs/jsonObject" },
+        "facets": {
+          "type": "array",
+          "maxItems": 32,
+          "items": { "$ref": "#/$defs/resolvedDefinition" }
+        },
+        "policies": {
+          "type": "array",
+          "maxItems": 32,
+          "items": { "$ref": "#/$defs/policyEvidence" }
+        }
+      }
+    },
+    "target": { "$ref": "#/$defs/target" },
+    "readSet": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "$ref": "#/$defs/readAssertion" } },
+    "requiredAdapterCapabilities": {
+      "type": "array",
+      "prefixItems": [{ "const": "materialize-file/v1" }],
+      "minItems": 1,
+      "maxItems": 1
+    },
+    "operations": { "type": "array", "minItems": 1, "maxItems": 4096, "items": { "$ref": "#/$defs/operation" } },
+    "diagnostics": { "type": "array", "maxItems": 1024, "items": { "$ref": "#/$defs/diagnostic" } },
+    "planDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "authorityId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[a-z0-9][a-z0-9._/-]*$"
+    },
+    "artifactId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 214,
+      "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/-]*$"
+    },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$" },
+    "definitionRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "$ref": "#/$defs/authorityId" },
+        "contractVersion": { "type": "integer", "minimum": 1, "maximum": 2147483647 }
+      }
+    },
+    "configuredDefinition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref"],
+      "properties": {
+        "ref": { "$ref": "#/$defs/definitionRef" },
+        "parameters": { "$ref": "#/$defs/jsonObject" }
+      }
+    },
+    "intent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "compositionId", "targetRef"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "compositionId": { "$ref": "#/$defs/authorityId" },
+        "targetRef": { "$ref": "#/$defs/authorityId" },
+        "recipeParameters": { "$ref": "#/$defs/jsonObject" },
+        "facets": {
+          "type": "array",
+          "maxItems": 32,
+          "items": { "$ref": "#/$defs/configuredDefinition" }
+        }
+      }
+    },
+    "resolvedDefinition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "parameters"],
+      "properties": {
+        "ref": { "$ref": "#/$defs/definitionRef" },
+        "parameters": { "$ref": "#/$defs/jsonObject" }
+      }
+    },
+    "policyEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "parameters", "outcome"],
+      "properties": {
+        "ref": { "$ref": "#/$defs/definitionRef" },
+        "parameters": { "$ref": "#/$defs/jsonObject" },
+        "outcome": { "const": "passed" }
+      }
+    },
+    "jsonObject": {
+      "type": "object",
+      "maxProperties": 128,
+      "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+    },
+    "jsonValue": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
+        { "type": "string", "maxLength": 65536 },
+        { "type": "array", "maxItems": 1024, "items": { "$ref": "#/$defs/jsonValue" } },
+        { "$ref": "#/$defs/jsonObject" }
+      ]
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "role", "path", "packageName"],
+      "properties": {
+        "id": { "$ref": "#/$defs/authorityId" },
+        "role": { "$ref": "#/$defs/authorityId" },
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "packageName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 214,
+          "pattern": "^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$"
+        },
+        "ownerDocument": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^[^\\u0000-\\u001F]+$"
+        }
+      }
+    },
+    "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 }
+      }
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "path", "precondition", "after", "causes"],
+      "properties": {
+        "id": { "$ref": "#/$defs/artifactId" },
+        "kind": { "const": "materialize-file" },
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "precondition": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["state"],
+          "properties": { "state": { "const": "absent" } }
+        },
+        "after": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["digest", "size", "mode", "mediaType", "contentBase64"],
+          "properties": {
+            "digest": { "$ref": "#/$defs/digest" },
+            "size": { "type": "integer", "minimum": 0, "maximum": 1048576 },
+            "mode": { "const": "0644" },
+            "mediaType": { "type": "string", "minLength": 1, "maxLength": 128 },
+            "contentBase64": { "type": "string", "maxLength": 1398104, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }
+          }
+        },
+        "causes": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/artifactId" } }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "severity", "phase", "subject", "message", "remediation"],
+      "properties": {
+        "ruleId": { "$ref": "#/$defs/artifactId" },
+        "severity": { "enum": ["error", "info", "warning"] },
+        "phase": { "enum": ["apply", "composition", "input", "planning", "policy", "recovery"] },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "message": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "remediation": { "type": "string", "minLength": 1, "maxLength": 1000 }
+      }
+    }
+  }
+}

package/schemas/scaffold-receipt/v1.schema.json

@@ -0,0 +1,299 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/scaffold-receipt/v1",
+  "title": "Scaffold Receipt v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocolVersion", "planDigest", "adapter", "outcome", "commit", "operations", "diagnostics", "receiptDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "planDigest": { "$ref": "#/$defs/digest" },
+    "adapter": {
+      "oneOf": [
+        { "$ref": "#/$defs/filesystemAdapter" },
+        { "$ref": "#/$defs/memoryAdapter" }
+      ]
+    },
+    "outcome": { "enum": ["already-applied", "applied", "failed-recovered", "recovery-required", "rejected"] },
+    "commit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "enum": ["committed", "recovered", "recovery-required", "rejected"] },
+        "atomicity": { "enum": ["journaled-recoverable", "memory-atomic"] }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "maxItems": 4096,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["operationId", "path", "outcome"],
+        "properties": {
+          "operationId": { "$ref": "#/$defs/id" },
+          "path": { "$ref": "#/$defs/repositoryPath" },
+          "outcome": { "enum": ["already-satisfied", "applied", "conflict", "not-applied", "recovered"] },
+          "resultDigest": { "$ref": "#/$defs/digest" }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "outcome": { "enum": ["already-satisfied", "applied", "recovered"] }
+              },
+              "required": ["outcome"]
+            },
+            "then": {
+              "properties": { "resultDigest": { "$ref": "#/$defs/digest" } },
+              "required": ["resultDigest"]
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "outcome": { "enum": ["conflict", "not-applied"] }
+              },
+              "required": ["outcome"]
+            },
+            "then": { "properties": { "resultDigest": false } }
+          }
+        ]
+      }
+    },
+    "diagnostics": { "type": "array", "maxItems": 1024, "items": { "$ref": "#/$defs/diagnostic" } },
+    "receiptDigest": { "$ref": "#/$defs/digest" }
+  },
+  "allOf": [
+    {
+      "oneOf": [
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/filesystemAdapter" },
+            "outcome": { "const": "applied" },
+            "commit": { "$ref": "#/$defs/filesystemCommitted" },
+            "operations": { "$ref": "#/$defs/appliedOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/memoryAdapter" },
+            "outcome": { "const": "applied" },
+            "commit": { "$ref": "#/$defs/memoryCommitted" },
+            "operations": { "$ref": "#/$defs/appliedOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/filesystemAdapter" },
+            "outcome": { "const": "already-applied" },
+            "commit": { "$ref": "#/$defs/filesystemCommitted" },
+            "operations": { "$ref": "#/$defs/alreadyAppliedOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/memoryAdapter" },
+            "outcome": { "const": "already-applied" },
+            "commit": { "$ref": "#/$defs/memoryCommitted" },
+            "operations": { "$ref": "#/$defs/alreadyAppliedOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/filesystemAdapter" },
+            "outcome": { "const": "failed-recovered" },
+            "commit": { "$ref": "#/$defs/filesystemRecovered" },
+            "operations": { "$ref": "#/$defs/failedRecoveredOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/filesystemAdapter" },
+            "outcome": { "const": "recovery-required" },
+            "commit": { "$ref": "#/$defs/filesystemRecoveryRequired" },
+            "operations": { "$ref": "#/$defs/recoveryRequiredOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/filesystemAdapter" },
+            "outcome": { "const": "rejected" },
+            "commit": { "$ref": "#/$defs/filesystemRejected" },
+            "operations": { "$ref": "#/$defs/incompleteOperations" }
+          }
+        },
+        {
+          "properties": {
+            "adapter": { "$ref": "#/$defs/memoryAdapter" },
+            "outcome": { "const": "rejected" },
+            "commit": { "$ref": "#/$defs/memoryRejected" },
+            "operations": { "$ref": "#/$defs/incompleteOperations" }
+          }
+        }
+      ]
+    }
+  ],
+  "$defs": {
+    "filesystemAdapter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "const": "foundation.filesystem/v1" },
+        "contractVersion": { "const": 1 }
+      }
+    },
+    "memoryAdapter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "const": "foundation.memory/v1" },
+        "contractVersion": { "const": 1 }
+      }
+    },
+    "filesystemCommitted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "const": "committed" },
+        "atomicity": { "const": "journaled-recoverable" }
+      }
+    },
+    "memoryCommitted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "const": "committed" },
+        "atomicity": { "const": "memory-atomic" }
+      }
+    },
+    "filesystemRecovered": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "const": "recovered" },
+        "atomicity": { "const": "journaled-recoverable" }
+      }
+    },
+    "filesystemRecoveryRequired": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "const": "recovery-required" },
+        "atomicity": { "const": "journaled-recoverable" }
+      }
+    },
+    "filesystemRejected": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "const": "rejected" },
+        "atomicity": { "const": "journaled-recoverable" }
+      }
+    },
+    "memoryRejected": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "atomicity"],
+      "properties": {
+        "state": { "const": "rejected" },
+        "atomicity": { "const": "memory-atomic" }
+      }
+    },
+    "appliedOperations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "enum": ["already-satisfied", "applied"] }
+        }
+      },
+      "contains": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "const": "applied" }
+        }
+      },
+      "minContains": 1
+    },
+    "alreadyAppliedOperations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "const": "already-satisfied" }
+        }
+      }
+    },
+    "failedRecoveredOperations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "enum": ["already-satisfied", "recovered"] }
+        }
+      }
+    },
+    "incompleteOperations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "enum": ["already-satisfied", "conflict", "not-applied"] }
+        }
+      }
+    },
+    "recoveryRequiredOperations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "enum": ["already-satisfied", "conflict", "not-applied"] }
+        }
+      },
+      "contains": {
+        "type": "object",
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "enum": ["conflict", "not-applied"] }
+        }
+      },
+      "minContains": 1
+    },
+    "id": { "type": "string", "minLength": 1, "maxLength": 214, "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/-]*$" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$" },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "severity", "phase", "subject", "message", "remediation"],
+      "properties": {
+        "ruleId": { "$ref": "#/$defs/id" },
+        "severity": { "enum": ["error", "info", "warning"] },
+        "phase": { "enum": ["apply", "composition", "input", "planning", "policy", "recovery"] },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "message": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "remediation": { "type": "string", "minLength": 1, "maxLength": 1000 }
+      }
+    }
+  }
+}

package/schemas/scaffold-target-catalog/v1.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/scaffold-target-catalog/v1",
+  "title": "Scaffold Target Catalog v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "packages"],
+  "properties": {
+    "version": { "const": 1 },
+    "packages": {
+      "type": "array",
+      "maxItems": 4096,
+      "items": { "$ref": "#/$defs/target" }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[a-z0-9][a-z0-9._/-]*$"
+    },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$"
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "role", "path", "package_name"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "role": { "$ref": "#/$defs/id" },
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "package_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 214,
+          "pattern": "^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$"
+        },
+        "owner_document": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^[^\\u0000-\\u001F]+$"
+        }
+      }
+    }
+  }
+}