@kungfu-tech/buildchain 3.0.9-alpha.9 → 4.0.0-alpha.0

package/contracts/v4-release-activation-shadow-v1.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schema/v4-release-activation-shadow-v1.schema.json",
+  "title": "Buildchain v4 release activation shadow request",
+  "description": "The sole closed schema authority for qualified release activation planning and deterministic resume projection. It grants no provider or production write authority.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "declaredAt",
+    "transactionRoot",
+    "qualificationRoot",
+    "authorityRoot",
+    "policyRoot",
+    "steps",
+    "events"
+  ],
+  "properties": {
+    "schema": { "const": "buildchain-v4-release-activation-request/v1" },
+    "declaredAt": { "$ref": "#/$defs/clock" },
+    "transactionRoot": { "$ref": "#/$defs/root" },
+    "qualificationRoot": {
+      "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+    },
+    "authorityRoot": { "$ref": "#/$defs/root" },
+    "policyRoot": { "$ref": "#/$defs/root" },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/step" }
+    },
+    "events": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/event" }
+    }
+  },
+  "$defs": {
+    "root": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "clock": {
+      "type": "string",
+      "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "token": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "ordinal": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "transactionRoot",
+        "capabilityId",
+        "subjectRoot",
+        "targetRoot",
+        "authorityRoot",
+        "policyRoot"
+      ],
+      "properties": {
+        "schema": { "const": "buildchain-v4-provider-operation-identity/v1" },
+        "transactionRoot": { "$ref": "#/$defs/root" },
+        "capabilityId": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$"
+        },
+        "subjectRoot": { "$ref": "#/$defs/root" },
+        "targetRoot": { "$ref": "#/$defs/root" },
+        "authorityRoot": { "$ref": "#/$defs/root" },
+        "policyRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "dependencies",
+        "operation",
+        "compensationBoundaryRoot"
+      ],
+      "properties": {
+        "id": { "$ref": "#/$defs/token" },
+        "dependencies": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/token" }
+        },
+        "operation": { "$ref": "#/$defs/operation" },
+        "compensationBoundaryRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "event": {
+      "oneOf": [
+        { "$ref": "#/$defs/attempt" },
+        { "$ref": "#/$defs/observation" },
+        { "$ref": "#/$defs/reconciliation" },
+        { "$ref": "#/$defs/confirmation" }
+      ]
+    },
+    "attempt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "stepId", "ordinal", "attemptedAt", "effectRoot"],
+      "properties": {
+        "kind": { "const": "attempt" },
+        "stepId": { "$ref": "#/$defs/token" },
+        "ordinal": { "$ref": "#/$defs/ordinal" },
+        "attemptedAt": { "$ref": "#/$defs/clock" },
+        "effectRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "observation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "stepId",
+        "ordinal",
+        "observedAt",
+        "status",
+        "evidenceRoots"
+      ],
+      "properties": {
+        "kind": { "const": "observation" },
+        "stepId": { "$ref": "#/$defs/token" },
+        "ordinal": { "$ref": "#/$defs/ordinal" },
+        "observedAt": { "$ref": "#/$defs/clock" },
+        "status": { "enum": ["succeeded", "failed", "unknown"] },
+        "evidenceRoots": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/root" }
+        }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "stepId",
+        "ordinal",
+        "reconciledAt",
+        "disposition",
+        "authorityRoot"
+      ],
+      "properties": {
+        "kind": { "const": "reconciliation" },
+        "stepId": { "$ref": "#/$defs/token" },
+        "ordinal": { "$ref": "#/$defs/ordinal" },
+        "reconciledAt": { "$ref": "#/$defs/clock" },
+        "disposition": { "enum": ["retry", "confirm", "terminal"] },
+        "authorityRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "confirmation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "stepId",
+        "ordinal",
+        "confirmedAt",
+        "outcome",
+        "authorityRoot"
+      ],
+      "properties": {
+        "kind": { "const": "confirmation" },
+        "stepId": { "$ref": "#/$defs/token" },
+        "ordinal": { "$ref": "#/$defs/ordinal" },
+        "confirmedAt": { "$ref": "#/$defs/clock" },
+        "outcome": { "enum": ["confirmed", "rejected"] },
+        "authorityRoot": { "$ref": "#/$defs/root" }
+      }
+    }
+  }
+}

package/contracts/v4-stable-publication-fence-v1.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schema/v4-stable-publication-fence-v1.schema.json",
+  "title": "Buildchain v4 stable publication shadow fence request",
+  "description": "The sole closed schema authority for independently qualified stable-candidate publication planning. It grants no provider, ref, package, image, release, or production write authority.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "declaredAt",
+    "candidate",
+    "qualification",
+    "publisherAuthorityRoot",
+    "targets"
+  ],
+  "properties": {
+    "schema": { "const": "buildchain-v4-stable-publication-request/v1" },
+    "declaredAt": { "$ref": "#/$defs/clock" },
+    "candidate": { "$ref": "#/$defs/candidate" },
+    "qualification": { "$ref": "#/$defs/qualification" },
+    "publisherAuthorityRoot": { "$ref": "#/$defs/root" },
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/target" }
+    }
+  },
+  "$defs": {
+    "root": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "clock": {
+      "type": "string",
+      "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "token": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "rootSet": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/root" }
+    },
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "generation",
+        "commit",
+        "sourceRoot",
+        "metadataRoot",
+        "journalRoot",
+        "protectedAncestryRoot"
+      ],
+      "properties": {
+        "generation": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        },
+        "sourceRoot": { "$ref": "#/$defs/root" },
+        "metadataRoot": { "$ref": "#/$defs/root" },
+        "journalRoot": { "$ref": "#/$defs/root" },
+        "protectedAncestryRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "qualification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "authorityGeneration",
+        "qualifiedCandidateRoot",
+        "qualifierAuthorityRoot",
+        "sealRoot",
+        "sourceRoot",
+        "metadataRoot",
+        "journalRoot",
+        "protectedAncestryRoot",
+        "providerConfirmationRoots"
+      ],
+      "properties": {
+        "mode": { "enum": ["n-minus-one", "independent-seal"] },
+        "authorityGeneration": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "qualifiedCandidateRoot": { "$ref": "#/$defs/root" },
+        "qualifierAuthorityRoot": { "$ref": "#/$defs/root" },
+        "sealRoot": { "$ref": "#/$defs/root" },
+        "sourceRoot": { "$ref": "#/$defs/root" },
+        "metadataRoot": { "$ref": "#/$defs/root" },
+        "journalRoot": { "$ref": "#/$defs/root" },
+        "protectedAncestryRoot": { "$ref": "#/$defs/root" },
+        "providerConfirmationRoots": { "$ref": "#/$defs/rootSet" }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "desired", "providerConfirmationRoot"],
+      "properties": {
+        "id": { "$ref": "#/$defs/token" },
+        "kind": {
+          "enum": ["stable-ref", "npm-tag", "oci-tag", "github-release"]
+        },
+        "desired": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "pattern": "^[!-~]+$"
+        },
+        "providerConfirmationRoot": { "$ref": "#/$defs/root" }
+      }
+    }
+  }
+}

package/contracts/v4-stage-capsule-resume-v1.schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schema/v4-stage-capsule-resume-v1.schema.json",
+  "title": "Buildchain v4 Stage Capsule resume planner contract suite",
+  "description": "Closed pure request and plan contracts for deterministic Stage Capsule resume decisions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "request", "plan"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "request": { "$ref": "#/$defs/request" },
+    "plan": { "$ref": "#/$defs/plan" }
+  },
+  "$defs": {
+    "root": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "clock": {
+      "type": "string",
+      "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "token": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "retentionPromise": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["class", "retainUntil"],
+      "properties": {
+        "class": { "$ref": "#/$defs/token" },
+        "retainUntil": { "$ref": "#/$defs/clock" }
+      }
+    },
+    "candidate": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["capsule", "availability"],
+      "properties": {
+        "capsule": {
+          "$ref": "v4-stage-capsule-v1.schema.json#/$defs/capsule"
+        },
+        "availability": {
+          "$ref": "v4-stage-capsule-v1.schema.json#/$defs/availability"
+        }
+      }
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "dependencies",
+        "expectedIdentity",
+        "expectedRetentionPromise",
+        "candidate"
+      ],
+      "properties": {
+        "key": { "$ref": "#/$defs/token" },
+        "dependencies": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/token" }
+        },
+        "expectedIdentity": {
+          "$ref": "v4-stage-capsule-v1.schema.json#/$defs/identity"
+        },
+        "expectedRetentionPromise": {
+          "$ref": "#/$defs/retentionPromise"
+        },
+        "candidate": { "$ref": "#/$defs/candidate" }
+      }
+    },
+    "effect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "provider",
+        "afterStages",
+        "providerReadback",
+        "mutation"
+      ],
+      "properties": {
+        "id": { "$ref": "#/$defs/token" },
+        "kind": { "$ref": "#/$defs/token" },
+        "provider": { "$ref": "#/$defs/token" },
+        "afterStages": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/token" }
+        },
+        "providerReadback": { "const": true },
+        "mutation": { "const": false }
+      }
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "evaluatedAt", "nodes", "targets", "effects"],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-stage-capsule-resume-request/v1"
+        },
+        "evaluatedAt": { "$ref": "#/$defs/clock" },
+        "nodes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/node" }
+        },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/token" }
+        },
+        "effects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/effect" }
+        }
+      }
+    },
+    "cause": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["field", "expectedRoot", "observedRoot"],
+      "properties": {
+        "field": { "$ref": "#/$defs/token" },
+        "expectedRoot": { "$ref": "#/$defs/root" },
+        "observedRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "read": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "name", "root"],
+      "properties": {
+        "kind": { "$ref": "#/$defs/token" },
+        "name": { "$ref": "#/$defs/token" },
+        "root": { "$ref": "#/$defs/root" }
+      }
+    },
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "stageKey",
+        "platform",
+        "stage",
+        "decision",
+        "execution",
+        "reasonCode",
+        "capsuleRoot",
+        "availabilityRoot",
+        "invalidationCauses",
+        "requiredReads"
+      ],
+      "properties": {
+        "stageKey": { "$ref": "#/$defs/token" },
+        "platform": { "$ref": "#/$defs/token" },
+        "stage": { "$ref": "#/$defs/token" },
+        "decision": { "enum": ["reuse", "rebuild", "reject"] },
+        "execution": { "enum": ["reuse", "rebuild"] },
+        "reasonCode": { "$ref": "#/$defs/token" },
+        "capsuleRoot": {
+          "anyOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "availabilityRoot": {
+          "anyOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "invalidationCauses": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/cause" }
+        },
+        "requiredReads": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/read" }
+        }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "mode",
+        "productionAuthority",
+        "evaluatedAt",
+        "decisions",
+        "requiredRestores",
+        "requiredStages",
+        "requiredEffects",
+        "planRoot"
+      ],
+      "properties": {
+        "schema": { "const": "buildchain-v4-stage-capsule-resume-plan/v1" },
+        "mode": { "const": "shadow-only" },
+        "productionAuthority": { "const": "v3" },
+        "evaluatedAt": { "$ref": "#/$defs/clock" },
+        "decisions": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/decision" }
+        },
+        "requiredRestores": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/token" }
+        },
+        "requiredStages": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/token" }
+        },
+        "requiredEffects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/effect" }
+        },
+        "planRoot": { "$ref": "#/$defs/root" }
+      }
+    }
+  }
+}

package/contracts/v4-stage-capsule-store-v1.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schema/v4-stage-capsule-store-v1.schema.json",
+  "title": "Buildchain v4 Stage Capsule store contract suite",
+  "description": "Closed provider-neutral contracts for exact content manifests, retention observations, rooted transport facts, and immutable store receipts.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "manifest",
+    "retentionState",
+    "transport",
+    "receipt"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "manifest": { "$ref": "#/$defs/manifest" },
+    "retentionState": { "$ref": "#/$defs/retentionState" },
+    "transport": { "$ref": "#/$defs/transport" },
+    "receipt": { "$ref": "#/$defs/receipt" }
+  },
+  "$defs": {
+    "root": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "clock": {
+      "type": "string",
+      "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "token": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "contentEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "root", "size"],
+      "properties": {
+        "name": { "$ref": "#/$defs/token" },
+        "root": { "$ref": "#/$defs/root" },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "manifest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "entries", "manifestRoot"],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-stage-capsule-output-manifest/v1"
+        },
+        "entries": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/contentEntry" }
+        },
+        "manifestRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "retentionState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "capsuleRoot",
+        "promiseRoot",
+        "evaluatedAt",
+        "status",
+        "stateRoot"
+      ],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-stage-capsule-retention-state/v1"
+        },
+        "capsuleRoot": { "$ref": "#/$defs/root" },
+        "promiseRoot": { "$ref": "#/$defs/root" },
+        "evaluatedAt": { "$ref": "#/$defs/clock" },
+        "status": { "enum": ["retained", "expired"] },
+        "stateRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "transport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "provider",
+        "mode",
+        "locatorRoot",
+        "observedAt",
+        "transportRoot"
+      ],
+      "properties": {
+        "schema": { "const": "buildchain-v4-stage-capsule-transport/v1" },
+        "provider": {
+          "enum": ["local-filesystem", "github-artifacts", "s3-compatible"]
+        },
+        "mode": {
+          "enum": ["local-reference", "effect-disabled", "fixture-backed"]
+        },
+        "locatorRoot": { "$ref": "#/$defs/root" },
+        "observedAt": { "$ref": "#/$defs/clock" },
+        "transportRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "operation",
+        "recordedAt",
+        "capsuleRoot",
+        "manifestRoot",
+        "retentionStateRoot",
+        "availabilityRoot",
+        "transportRoot",
+        "qualificationRoot",
+        "outcome",
+        "faultCode",
+        "receiptRoot"
+      ],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-stage-capsule-store-receipt/v1"
+        },
+        "operation": { "enum": ["put", "locate", "restore", "quarantine"] },
+        "recordedAt": { "$ref": "#/$defs/clock" },
+        "capsuleRoot": { "$ref": "#/$defs/root" },
+        "manifestRoot": { "$ref": "#/$defs/root" },
+        "retentionStateRoot": { "$ref": "#/$defs/root" },
+        "availabilityRoot": { "$ref": "#/$defs/root" },
+        "transportRoot": { "$ref": "#/$defs/root" },
+        "qualificationRoot": { "$ref": "#/$defs/root" },
+        "outcome": {
+          "enum": [
+            "stored",
+            "already-stored",
+            "located",
+            "restored",
+            "quarantined"
+          ]
+        },
+        "faultCode": { "type": "null" },
+        "receiptRoot": { "$ref": "#/$defs/root" }
+      }
+    }
+  }
+}