@agent-teams/engineering-foundation 0.10.0 → 0.12.0

package/schemas/document-intent/v1.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/document-intent/v1",
+  "title": "Document Intent",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "type", "id", "title", "owner", "summary"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "type": { "$ref": "#/$defs/lowerId" },
+    "id": { "$ref": "#/$defs/opaqueId" },
+    "title": { "$ref": "#/$defs/title" },
+    "owner": { "$ref": "#/$defs/opaqueId" },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 1000 },
+    "related": {
+      "type": "array",
+      "maxItems": 128,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/opaqueId" }
+    },
+    "additionalMetadata": { "$ref": "#/$defs/jsonObject1" }
+  },
+  "$defs": {
+    "lowerId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+    "opaqueId": { "type": "string", "minLength": 1, "maxLength": 214, "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/-]*$" },
+    "title": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" },
+    "jsonScalar": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
+        { "type": "string", "maxLength": 4096 }
+      ]
+    },
+    "jsonObject1": { "type": "object", "maxProperties": 64, "additionalProperties": { "$ref": "#/$defs/jsonValue1" } },
+    "jsonValue1": {
+      "oneOf": [
+        { "$ref": "#/$defs/jsonScalar" },
+        { "type": "array", "maxItems": 128, "items": { "$ref": "#/$defs/jsonValue2" } },
+        { "$ref": "#/$defs/jsonObject2" }
+      ]
+    },
+    "jsonObject2": { "type": "object", "maxProperties": 64, "additionalProperties": { "$ref": "#/$defs/jsonValue2" } },
+    "jsonValue2": {
+      "oneOf": [
+        { "$ref": "#/$defs/jsonScalar" },
+        { "type": "array", "maxItems": 128, "items": { "$ref": "#/$defs/jsonValue3" } },
+        { "$ref": "#/$defs/jsonObject3" }
+      ]
+    },
+    "jsonObject3": { "type": "object", "maxProperties": 64, "additionalProperties": { "$ref": "#/$defs/jsonValue3" } },
+    "jsonValue3": {
+      "oneOf": [
+        { "$ref": "#/$defs/jsonScalar" },
+        { "type": "array", "maxItems": 128, "items": { "$ref": "#/$defs/jsonScalar" } },
+        { "type": "object", "maxProperties": 64, "additionalProperties": { "$ref": "#/$defs/jsonScalar" } }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/document-plan/v1",
+  "title": "Document Plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocolVersion", "compiler", "projectId", "intent", "intentDigest", "authority", "selectedOwner", "identityProjection", "referencedDocuments", "destination", "expectedParent", "destinationPrecondition", "output", "requiredAdapterCapabilities", "diagnostics", "planDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "compiler": { "$ref": "#/$defs/compiler" },
+    "projectId": { "$ref": "#/$defs/lowerId" },
+    "intent": { "$ref": "https://agent-teams.ai/schemas/document-intent/v1" },
+    "intentDigest": { "$ref": "#/$defs/digest" },
+    "authority": { "$ref": "#/$defs/authority" },
+    "selectedOwner": { "$ref": "#/$defs/selectedOwner" },
+    "identityProjection": { "$ref": "#/$defs/identityProjection" },
+    "referencedDocuments": {
+      "type": "array",
+      "maxItems": 128,
+      "items": { "$ref": "#/$defs/referencedDocument" }
+    },
+    "destination": { "$ref": "#/$defs/repositoryPath" },
+    "expectedParent": { "$ref": "#/$defs/expectedParent" },
+    "destinationPrecondition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": { "state": { "const": "absent" } }
+    },
+    "output": { "$ref": "#/$defs/output" },
+    "requiredAdapterCapabilities": {
+      "type": "array",
+      "prefixItems": [{ "const": "create-file-no-replace/v1" }],
+      "minItems": 1,
+      "maxItems": 1
+    },
+    "diagnostics": { "type": "array", "maxItems": 256, "items": { "$ref": "#/$defs/diagnostic" } },
+    "planDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "lowerId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+    "opaqueId": { "type": "string", "minLength": 1, "maxLength": 214, "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/-]*$" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "semver": { "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-]+)*)?$" },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.[A-Za-z0-9._@-]*)?(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$"
+    },
+    "compiler": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "buildIdentity"],
+      "properties": {
+        "id": { "const": "@agent-teams/engineering-foundation" },
+        "version": { "$ref": "#/$defs/semver" },
+        "buildIdentity": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "authoritySource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "digest", "size"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "digest": { "$ref": "#/$defs/digest" },
+        "size": { "type": "integer", "minimum": 1, "maximum": 4194304 }
+      }
+    },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["profile", "metadataSchema", "ownerCatalog", "template"],
+      "properties": {
+        "profile": { "$ref": "#/$defs/authoritySource" },
+        "metadataSchema": { "$ref": "#/$defs/authoritySource" },
+        "ownerCatalog": { "$ref": "#/$defs/authoritySource" },
+        "template": { "$ref": "#/$defs/authoritySource" }
+      }
+    },
+    "selectedOwner": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "membershipDigest"],
+      "properties": {
+        "id": { "$ref": "#/$defs/opaqueId" },
+        "membershipDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "identityProjection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["entryCount", "digest"],
+      "properties": {
+        "entryCount": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "referencedDocument": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "projectionDigest"],
+      "properties": {
+        "id": { "$ref": "#/$defs/opaqueId" },
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "projectionDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "expectedParent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "state", "ancestry"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "state": { "const": "directory" },
+        "ancestry": { "const": "real-directories" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "size", "mode", "mediaType", "contentBase64"],
+      "properties": {
+        "digest": { "$ref": "#/$defs/digest" },
+        "size": { "type": "integer", "minimum": 1, "maximum": 1048576 },
+        "mode": { "const": "0644" },
+        "mediaType": { "const": "text/markdown; charset=utf-8" },
+        "contentBase64": { "type": "string", "minLength": 4, "maxLength": 1398104, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "severity", "phase", "subject", "message"],
+      "properties": {
+        "ruleId": { "$ref": "#/$defs/opaqueId" },
+        "severity": { "enum": ["error", "info", "warning"] },
+        "phase": { "enum": ["authority", "input", "planning", "policy"] },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "message": { "type": "string", "minLength": 1, "maxLength": 1000 }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/document-receipt/v1",
+  "title": "Document Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocolVersion", "planDigest", "adapter", "destination", "outcome", "commit", "diagnostics", "receiptDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "planDigest": { "$ref": "#/$defs/digest" },
+    "adapter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "const": "foundation.filesystem/v1" },
+        "contractVersion": { "const": 1 }
+      }
+    },
+    "destination": { "$ref": "#/$defs/repositoryPath" },
+    "outcome": { "enum": ["applied", "already-applied", "authority-stale", "rejected", "recovery-required", "manual-recovery-required", "failed-before-publication", "cancelled"] },
+    "resultDigest": { "$ref": "#/$defs/digest" },
+    "commit": { "$ref": "#/$defs/commitObservation" },
+    "diagnostics": { "type": "array", "maxItems": 256, "items": { "$ref": "#/$defs/diagnostic" } },
+    "receiptDigest": { "$ref": "#/$defs/digest" }
+  },
+  "allOf": [
+    { "$ref": "#/$defs/appliedContract" },
+    { "$ref": "#/$defs/alreadyAppliedContract" },
+    { "$ref": "#/$defs/noResultContract" },
+    { "$ref": "#/$defs/recoveryContract" }
+  ],
+  "$defs": {
+    "opaqueId": { "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}(?:/|$))(?!.*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.[A-Za-z0-9._@-]*)?(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$"
+    },
+    "commitObservation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "publication", "atomicity", "recoverability"],
+      "properties": {
+        "state": { "enum": ["committed", "not-published", "preserved", "recovery-required", "manual-recovery-required"] },
+        "publication": { "enum": ["none", "preexisting-exact", "published", "unknown"] },
+        "atomicity": { "enum": ["not-applicable", "single-file-atomic-create"] },
+        "recoverability": { "enum": ["not-required", "journaled-recoverable", "preserved-for-recovery"] }
+      }
+    },
+    "appliedContract": {
+      "if": { "type": "object", "properties": { "outcome": { "const": "applied" } }, "required": ["outcome"] },
+      "then": {
+        "type": "object",
+        "required": ["resultDigest"],
+        "properties": {
+          "resultDigest": { "$ref": "#/$defs/digest" },
+          "commit": {
+            "type": "object",
+            "properties": {
+              "state": { "const": "committed" },
+              "publication": { "const": "published" },
+              "atomicity": { "const": "single-file-atomic-create" },
+              "recoverability": { "const": "not-required" }
+            }
+          }
+        }
+      }
+    },
+    "alreadyAppliedContract": {
+      "if": { "type": "object", "properties": { "outcome": { "const": "already-applied" } }, "required": ["outcome"] },
+      "then": {
+        "type": "object",
+        "required": ["resultDigest"],
+        "properties": {
+          "resultDigest": { "$ref": "#/$defs/digest" },
+          "commit": {
+            "type": "object",
+            "properties": {
+              "state": { "const": "committed" },
+              "publication": { "const": "preexisting-exact" },
+              "atomicity": { "const": "not-applicable" },
+              "recoverability": { "const": "not-required" }
+            }
+          }
+        }
+      }
+    },
+    "noResultContract": {
+      "if": { "type": "object", "properties": { "outcome": { "enum": ["authority-stale", "rejected", "failed-before-publication", "cancelled"] } }, "required": ["outcome"] },
+      "then": {
+        "type": "object",
+        "properties": {
+          "resultDigest": false,
+          "commit": {
+            "type": "object",
+            "properties": {
+              "state": { "const": "not-published" },
+              "publication": { "const": "none" },
+              "atomicity": { "const": "not-applicable" },
+              "recoverability": { "const": "not-required" }
+            }
+          }
+        }
+      }
+    },
+    "recoveryContract": {
+      "if": { "type": "object", "properties": { "outcome": { "enum": ["recovery-required", "manual-recovery-required"] } }, "required": ["outcome"] },
+      "then": {
+        "type": "object",
+        "properties": {
+          "resultDigest": false,
+          "commit": {
+            "type": "object",
+            "properties": {
+              "state": { "enum": ["preserved", "recovery-required", "manual-recovery-required"] },
+              "publication": { "enum": ["none", "published", "unknown"] },
+              "atomicity": { "enum": ["not-applicable", "single-file-atomic-create"] },
+              "recoverability": { "const": "preserved-for-recovery" }
+            }
+          }
+        }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "severity", "phase", "subject", "message"],
+      "properties": {
+        "ruleId": { "$ref": "#/$defs/opaqueId" },
+        "severity": { "enum": ["error", "info", "warning"] },
+        "phase": { "enum": ["apply", "authority", "input", "recovery"] },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "message": { "type": "string", "minLength": 1, "maxLength": 1000 }
+      }
+    }
+  }
+}

package/schemas/foundation-transaction-envelope/v2.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/foundation-transaction-envelope/v2",
+  "title": "Foundation Transaction Envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "operationKind", "recoveryHandler", "foundation", "adapterContractVersion", "payloadKind", "journal", "payloadDigest", "state", "envelopeDigest"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "operationKind": { "enum": ["document-authoring", "scaffolding"] },
+    "recoveryHandler": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "contractVersion"],
+      "properties": {
+        "id": { "enum": ["foundation.document-authoring", "foundation.scaffolding"] },
+        "contractVersion": { "const": 1 }
+      }
+    },
+    "foundation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "buildIdentity"],
+      "properties": {
+        "version": { "$ref": "#/$defs/semver" },
+        "buildIdentity": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "adapterContractVersion": { "const": 1 },
+    "payloadKind": { "enum": ["document-authoring-journal/v1", "scaffold-recovery-journal/v1"] },
+    "journal": {},
+    "payloadDigest": { "$ref": "#/$defs/digest" },
+    "state": { "enum": ["PREPARED", "PUBLISHING", "PUBLISHED"] },
+    "envelopeDigest": { "$ref": "#/$defs/digest" }
+  },
+  "allOf": [
+    { "$ref": "#/$defs/documentAuthoringEnvelope" },
+    { "$ref": "#/$defs/scaffoldingEnvelope" }
+  ],
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "semver": { "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-]+)*)?$" },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.[A-Za-z0-9._@-]*)?(?:/|$))[A-Za-z0-9._@-]+(?:/[A-Za-z0-9._@-]+)*$"
+    },
+    "documentJournal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "plan", "destination"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "plan": { "$ref": "https://agent-teams.ai/schemas/document-plan/v1" },
+        "destination": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "state"],
+          "properties": {
+            "path": { "$ref": "#/$defs/repositoryPath" },
+            "state": { "enum": ["pending", "preexisting", "publishing", "published"] }
+          }
+        },
+        "ownedTemporary": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "digest"],
+          "properties": {
+            "path": { "$ref": "#/$defs/repositoryPath" },
+            "digest": { "$ref": "#/$defs/digest" }
+          }
+        }
+      }
+    },
+    "documentAuthoringEnvelope": {
+      "if": { "type": "object", "properties": { "operationKind": { "const": "document-authoring" } }, "required": ["operationKind"] },
+      "then": {
+        "type": "object",
+        "properties": {
+          "recoveryHandler": {
+            "type": "object",
+            "properties": { "id": { "const": "foundation.document-authoring" } }
+          },
+          "payloadKind": { "const": "document-authoring-journal/v1" },
+          "journal": { "$ref": "#/$defs/documentJournal" }
+        }
+      }
+    },
+    "scaffoldingEnvelope": {
+      "if": { "type": "object", "properties": { "operationKind": { "const": "scaffolding" } }, "required": ["operationKind"] },
+      "then": {
+        "type": "object",
+        "properties": {
+          "recoveryHandler": {
+            "type": "object",
+            "properties": { "id": { "const": "foundation.scaffolding" } }
+          },
+          "payloadKind": { "const": "scaffold-recovery-journal/v1" },
+          "journal": { "$ref": "https://agent-teams.ai/schemas/scaffold-recovery-journal/v1" },
+          "state": { "const": "PREPARED" }
+        }
+      }
+    }
+  }
+}

package/schemas/quality-executable-specification-catalog/v1.schema.json

@@ -92,7 +92,7 @@
         "kind": { "const": "xstate" },
         "axes": {
           "type": "array",
-          "minItems": 2,
+          "description": "A possibly empty list of opaque consumer-owned topology identifiers; Foundation does not infer their semantics or independence.",
           "maxItems": 32,
           "uniqueItems": true,
           "items": { "$ref": "#/$defs/identifier" }