@agent-teams/docs-protocol-agent-teams 0.0.0 → 0.1.1

package/dist/qualification/qualification-v3-runner.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { QUALIFIED_DOCS_COHORT_V2_PACKAGES } from "../consumer-integration/composition/qualification-v3-boundary.js";
+import { observeDocsProtocolQualificationV3Lockfile } from "./qualification-v3-observer.js";
+const NONZERO_SHA256 = /^sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+const PACKAGE_KEYS = QUALIFIED_DOCS_COHORT_V2_PACKAGES.map(({ key }) => key);
+const CHECKS = Object.freeze([
+    "profile-v3",
+    "cohort-v2",
+    "five-package-closure",
+    "exact-package-versions",
+    "exact-package-integrities",
+    "schema-bindings-3-2-1",
+    "runtime-closure-digest"
+]);
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .toSorted(([left], [right]) => Buffer.compare(Buffer.from(left), Buffer.from(right)))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function digest(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+function hasExactKeys(value, keys) {
+    return Object.keys(value).toSorted().join("\u0000") === [...keys].toSorted().join("\u0000");
+}
+function assertEvidenceShape(evidence) {
+    if (!hasExactKeys(evidence, ["packages", "schemas", "runtimeClosureDigest"]) ||
+        !hasExactKeys(evidence.packages, PACKAGE_KEYS) ||
+        !hasExactKeys(evidence.schemas, ["consumerIntegration", "managedState", "docsProtocol"]) ||
+        !NONZERO_SHA256.test(evidence.runtimeClosureDigest)) {
+        throw new TypeError("Qualification v3 evidence is invalid or incomplete.");
+    }
+    for (const { key } of QUALIFIED_DOCS_COHORT_V2_PACKAGES) {
+        if (!hasExactKeys(evidence.packages[key], ["version", "integrity"])) {
+            throw new TypeError(`Qualification v3 package evidence for ${key} is invalid.`);
+        }
+    }
+}
+/**
+ * Admits only explicit profile-v3 evidence for the closed five-package Cohort v2.
+ * Collection/execution belongs to the disposable public-registry canary lane.
+ */
+export function runDocsProtocolQualificationV3(request) {
+    const lockfileObservation = observeDocsProtocolQualificationV3Lockfile(request);
+    assertEvidenceShape(request.evidence);
+    const { cohort } = request.profile;
+    for (const { key, name } of QUALIFIED_DOCS_COHORT_V2_PACKAGES) {
+        const expected = cohort.packages[key];
+        const observed = request.evidence.packages[key];
+        if (observed.version !== expected.version) {
+            throw new Error(`Qualification v3 version mismatch for ${name}.`);
+        }
+        if (observed.integrity !== expected.integrity) {
+            throw new Error(`Qualification v3 integrity mismatch for ${name}.`);
+        }
+    }
+    if (request.evidence.schemas.consumerIntegration !== 3 ||
+        request.evidence.schemas.managedState !== 2 ||
+        request.evidence.schemas.docsProtocol !== 1) {
+        throw new Error("Qualification v3 requires exact schema bindings 3/2/1.");
+    }
+    if (request.evidence.runtimeClosureDigest !== cohort.runtime.runtimeClosureDigest) {
+        throw new Error("Qualification v3 runtime closure digest mismatch.");
+    }
+    if (lockfileObservation.runtimeClosureDigest !== cohort.runtime.runtimeClosureDigest) {
+        throw new Error("Qualification v3 lockfile runtime closure digest mismatch.");
+    }
+    const body = Object.freeze({
+        schemaVersion: 3,
+        cohortAdmissible: true,
+        profileSchemaVersion: 3,
+        cohort: Object.freeze({
+            schemaVersion: 2,
+            cohortId: cohort.cohortId,
+            recordDigest: cohort.recordDigest,
+            qualificationEventDigest: cohort.qualificationEventDigest
+        }),
+        packages: Object.freeze(QUALIFIED_DOCS_COHORT_V2_PACKAGES.map(({ key, name }) => Object.freeze({ key, name, ...cohort.packages[key] }))),
+        schemas: Object.freeze({
+            consumerIntegration: 3,
+            managedState: 2,
+            docsProtocol: 1
+        }),
+        runtime: Object.freeze({ runtimeClosureDigest: cohort.runtime.runtimeClosureDigest }),
+        checks: CHECKS
+    });
+    return Object.freeze({ ...body, receiptDigest: digest(body) });
+}
+//# sourceMappingURL=qualification-v3-runner.js.map

package/dist/qualification/qualification-v3-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualification-v3-runner.js","sourceRoot":"","sources":["../../src/qualification/qualification-v3-runner.ts"],"names":[],"mappings":"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"}

package/dist/qualification/v3-contract.d.ts

@@ -0,0 +1,58 @@
+import type { ConsumerIntegrationDesiredStateV3, QualifiedDocsCohortBindingV2 } from "../consumer-integration/composition/qualification-v3-boundary.js";
+export type DocsProtocolQualificationCheckV3 = "profile-v3" | "cohort-v2" | "five-package-closure" | "exact-package-versions" | "exact-package-integrities" | "schema-bindings-3-2-1" | "runtime-closure-digest";
+export type DocsProtocolQualificationPackageKeyV3 = keyof QualifiedDocsCohortBindingV2["packages"];
+export interface DocsProtocolQualificationObservedPackageV3 {
+    readonly version: string;
+    readonly integrity: `sha512-${string}`;
+}
+/** Evidence observed by the release/canary lane, never inferred from installation shape. */
+export interface DocsProtocolQualificationEvidenceV3 {
+    readonly packages: Readonly<Record<DocsProtocolQualificationPackageKeyV3, DocsProtocolQualificationObservedPackageV3>>;
+    readonly schemas: {
+        readonly consumerIntegration: number;
+        readonly managedState: number;
+        readonly docsProtocol: number;
+    };
+    readonly runtimeClosureDigest: `sha256:${string}`;
+}
+export interface DocsProtocolQualificationV3Request {
+    readonly profile: ConsumerIntegrationDesiredStateV3;
+    readonly evidence: DocsProtocolQualificationEvidenceV3;
+    readonly lockfileBytes: Uint8Array;
+}
+export interface DocsProtocolQualificationLockfileObservationV3Request {
+    readonly profile: ConsumerIntegrationDesiredStateV3;
+    readonly lockfileBytes: Uint8Array;
+}
+export interface DocsProtocolQualificationLockfileObservationV3 {
+    readonly runtimeClosureDigest: `sha256:${string}`;
+}
+export interface DocsProtocolQualificationPackageReceiptV3 {
+    readonly key: DocsProtocolQualificationPackageKeyV3;
+    readonly name: `@agent-teams/${string}`;
+    readonly version: string;
+    readonly integrity: `sha512-${string}`;
+}
+export interface DocsProtocolQualificationReceiptV3 {
+    readonly schemaVersion: 3;
+    readonly receiptDigest: `sha256:${string}`;
+    readonly cohortAdmissible: true;
+    readonly profileSchemaVersion: 3;
+    readonly cohort: {
+        readonly schemaVersion: 2;
+        readonly cohortId: string;
+        readonly recordDigest: `sha256:${string}`;
+        readonly qualificationEventDigest: `sha256:${string}`;
+    };
+    readonly packages: readonly DocsProtocolQualificationPackageReceiptV3[];
+    readonly schemas: {
+        readonly consumerIntegration: 3;
+        readonly managedState: 2;
+        readonly docsProtocol: 1;
+    };
+    readonly runtime: {
+        readonly runtimeClosureDigest: `sha256:${string}`;
+    };
+    readonly checks: readonly DocsProtocolQualificationCheckV3[];
+}
+//# sourceMappingURL=v3-contract.d.ts.map

package/dist/qualification/v3-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3-contract.d.ts","sourceRoot":"","sources":["../../src/qualification/v3-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,4BAA4B,EAC7B,MAAM,kEAAkE,CAAC;AAE1E,MAAM,MAAM,gCAAgC,GACxC,YAAY,GACZ,WAAW,GACX,sBAAsB,GACtB,wBAAwB,GACxB,2BAA2B,GAC3B,uBAAuB,GACvB,wBAAwB,CAAC;AAE7B,MAAM,MAAM,qCAAqC,GAC/C,MAAM,4BAA4B,CAAC,UAAU,CAAC,CAAC;AAEjD,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,UAAU,MAAM,EAAE,CAAC;CACxC;AAED,4FAA4F;AAC5F,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAChC,qCAAqC,EACrC,0CAA0C,CAC3C,CAAC,CAAC;IACH,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,QAAQ,CAAC,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,mCAAmC,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;CACpC;AAED,MAAM,WAAW,qDAAqD;IACpE,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;CACpC;AAED,MAAM,WAAW,8CAA8C;IAC7D,QAAQ,CAAC,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,yCAAyC;IACxD,QAAQ,CAAC,GAAG,EAAE,qCAAqC,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,UAAU,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,UAAU,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;QAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,EAAE,UAAU,MAAM,EAAE,CAAC;QAC1C,QAAQ,CAAC,wBAAwB,EAAE,UAAU,MAAM,EAAE,CAAC;KACvD,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,SAAS,yCAAyC,EAAE,CAAC;IACxE,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAC;QAChC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;QACzB,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;KACnD,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,SAAS,gCAAgC,EAAE,CAAC;CAC9D"}

package/dist/qualification/v3-contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=v3-contract.js.map

package/dist/qualification/v3-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3-contract.js","sourceRoot":"","sources":["../../src/qualification/v3-contract.ts"],"names":[],"mappings":""}

package/package.json

@@ -6,8 +6,8 @@
     "url": "https://github.com/agent-teams-ai/engineering-foundation/issues"
   },
   "dependencies": {
-    "@agent-teams/docs-protocol": "0.4.1",
-    "@agent-teams/repository-mutation": "0.0.0",
+    "@agent-teams/docs-protocol": "0.5.1",
+    "@agent-teams/repository-mutation": "0.1.1",
     "ajv": "8.20.0",
     "jsonc-parser": "3.3.1",
     "yaml": "2.9.0"
@@ -62,5 +62,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.0"
+  "version": "0.1.1"
 }

package/schemas/docs-consumer-integration-profile/v3.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-integration-profile/v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "repository",
+    "integrationRoot",
+    "packageManager",
+    "profilePath",
+    "skillPath",
+    "callerWorkflowPath",
+    "managedStatePath",
+    "cohort",
+    "qualification"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 3 },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "id", "nameWithOwner"],
+      "properties": {
+        "provider": { "const": "github" },
+        "id": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "nameWithOwner": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
+        }
+      }
+    },
+    "integrationRoot": { "const": "." },
+    "packageManager": { "const": "pnpm" },
+    "profilePath": { "const": "architecture/foundation/docs-protocol.yaml" },
+    "skillPath": { "const": ".agents/skills/docs-authoring/SKILL.md" },
+    "callerWorkflowPath": { "const": ".github/workflows/docs-protocol.yml" },
+    "managedStatePath": {
+      "const": "architecture/foundation/docs-protocol-managed-state.json"
+    },
+    "qualification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contractPath", "gateCommand"],
+      "properties": {
+        "contractPath": {
+          "const": "architecture/foundation/docs-protocol-qualification.json"
+        },
+        "gateCommand": { "const": "pnpm docs:protocol:check" }
+      }
+    },
+    "governedDocsRoots": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 512,
+        "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]{1,255}(?:/[A-Za-z0-9._@-]{1,255})*$"
+      }
+    },
+    "cohort": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortBinding"
+    }
+  }
+}

package/schemas/docs-consumer-managed-state/v2.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-managed-state/v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "cohortId",
+    "cohortAuthority",
+    "repository",
+    "packages",
+    "schemas",
+    "runtime",
+    "profilePath",
+    "skillPath",
+    "callerWorkflowPath",
+    "managedStatePath",
+    "assets",
+    "stateDigest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "cohortId": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+    },
+    "cohortAuthority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "channel",
+        "recordDigest",
+        "qualificationEventDigest",
+        "eligibleAfter",
+        "upgradeFrom",
+        "rollbackTo"
+      ],
+      "properties": {
+        "channel": { "enum": ["rc", "stable"] },
+        "recordDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "qualificationEventDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "eligibleAfter": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+        },
+        "upgradeFrom": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortIds"
+        },
+        "rollbackTo": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortIds"
+        }
+      }
+    },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "id", "nameWithOwner"],
+      "properties": {
+        "provider": { "const": "github" },
+        "id": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "nameWithOwner": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
+        }
+      }
+    },
+    "packages": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortCore/properties/packages"
+    },
+    "schemas": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortCore/properties/schemas"
+    },
+    "runtime": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortCore/properties/runtime"
+    },
+    "profilePath": { "type": "string", "minLength": 1 },
+    "skillPath": { "type": "string", "minLength": 1 },
+    "callerWorkflowPath": { "type": "string", "minLength": 1 },
+    "managedStatePath": { "type": "string", "minLength": 1 },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "skillDigest",
+        "callerWorkflowDigest",
+        "assetCatalogDigest",
+        "transitionCatalogDigest",
+        "agentsRouteDigest",
+        "docsScriptsDigest"
+      ],
+      "properties": {
+        "skillDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "callerWorkflowDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "assetCatalogDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "transitionCatalogDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "agentsRouteDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "docsScriptsDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        }
+      }
+    },
+    "stateDigest": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+    }
+  }
+}

package/schemas/docs-consumer-restoration-execution/v1.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-restoration-execution/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "command",
+    "outcome",
+    "issues"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "command": {
+      "const": "consumer.restore"
+    },
+    "outcome": {
+      "enum": [
+        "blocked",
+        "restored",
+        "activated-v1"
+      ]
+    },
+    "issues": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "code",
+          "severity",
+          "subject",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^[A-Z0-9_]+$",
+            "maxLength": 128
+          },
+          "severity": {
+            "enum": [
+              "error",
+              "warning"
+            ]
+          },
+          "subject": {
+            "type": "string",
+            "maxLength": 2048
+          },
+          "message": {
+            "type": "string",
+            "maxLength": 4096
+          }
+        }
+      }
+    },
+    "receipt": {
+      "$ref": "https://agent-teams.ai/schemas/known-file-transaction-receipt/v1"
+    },
+    "proofDigest": {
+      "$ref": "#/$defs/sha256"
+    },
+    "inversePlanDigest": {
+      "$ref": "#/$defs/sha256"
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "enum": [
+              "restored",
+              "activated-v1"
+            ]
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "proofDigest",
+          "inversePlanDigest"
+        ],
+        "properties": {
+          "proofDigest": {
+            "$ref": "#/$defs/sha256"
+          },
+          "inversePlanDigest": {
+            "$ref": "#/$defs/sha256"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "restored"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "receipt"
+        ],
+        "properties": {
+          "receipt": {
+            "$ref": "https://agent-teams.ai/schemas/known-file-transaction-receipt/v1"
+          }
+        }
+      }
+    }
+  ]
+}

package/schemas/docs-consumer-upgrade-execution/v1.schema.json

@@ -6,8 +6,8 @@
   "required": ["schemaVersion", "command", "outcome", "issues"],
   "properties": {
     "schemaVersion": { "const": 1 },
-    "command": { "const": "consumer.upgrade" },
-    "outcome": { "enum": ["blocked", "current", "upgraded"] },
+    "command": { "enum": ["consumer.upgrade", "consumer.finalize"] },
+    "outcome": { "enum": ["blocked", "current", "upgraded", "prepared"] },
     "issues": {
       "type": "array",
       "maxItems": 64,
@@ -36,9 +36,45 @@
         "qualificationEventDigest": { "$ref": "#/$defs/sha256" }
       }
     },
+    "restoration": { "$ref": "#/$defs/retained" },
+    "preparation": { "$ref": "#/$defs/retained" },
     "receipt": { "$ref": "https://agent-teams.ai/schemas/known-file-transaction-receipt/v1" }
   },
   "$defs": {
+    "retained": {
+      "type": "object", "additionalProperties": false, "required": ["path", "digest"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "digest": { "$ref": "#/$defs/sha256" }
+      }
+    },
     "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
-  }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "outcome": { "const": "prepared" } } },
+      "then": {
+        "required": ["preparation"],
+        "properties": {
+          "command": { "const": "consumer.upgrade" },
+          "preparation": { "$ref": "#/$defs/retained" },
+          "receipt": false, "restoration": false
+        }
+      }
+    },
+    {
+      "if": { "properties": { "command": { "const": "consumer.finalize" } } },
+      "then": {
+        "properties": { "outcome": { "enum": ["blocked", "upgraded"] }, "preparation": false },
+        "if": { "properties": { "outcome": { "const": "upgraded" } } },
+        "then": {
+          "required": ["receipt", "restoration"],
+          "properties": {
+            "receipt": { "$ref": "https://agent-teams.ai/schemas/known-file-transaction-receipt/v1" },
+            "restoration": { "$ref": "#/$defs/retained" }
+          }
+        }
+      }
+    }
+  ]
 }