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

package/contracts/v4-host-contract-v1.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/v4-host-contract-v1.schema.json",
+  "title": "Buildchain v4 Host Contract",
+  "oneOf": [{ "$ref": "#/$defs/request" }, { "$ref": "#/$defs/response" }],
+  "$defs": {
+    "encodedBytes": {
+      "type": "object",
+      "required": ["encoding", "bytes"],
+      "additionalProperties": false,
+      "properties": {
+        "encoding": { "const": "base64" },
+        "bytes": { "type": "string", "contentEncoding": "base64" }
+      }
+    },
+    "command": {
+      "type": "object",
+      "required": ["id", "arguments"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "arguments": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "request": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "contract",
+        "protocolVersion",
+        "requestId",
+        "command",
+        "input",
+        "requiredCapabilities",
+        "timeoutMs"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "contract": { "const": "kungfu-buildchain-v4-host-request" },
+        "protocolVersion": { "const": "1.0" },
+        "requestId": { "type": "string", "minLength": 1 },
+        "command": { "$ref": "#/$defs/command" },
+        "input": { "$ref": "#/$defs/encodedBytes" },
+        "requiredCapabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 30000
+        }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["code", "message", "retryable"],
+      "additionalProperties": false,
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string" },
+        "retryable": { "type": "boolean" }
+      }
+    },
+    "response": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "contract",
+        "protocolVersion",
+        "requestId",
+        "status",
+        "host",
+        "command",
+        "output",
+        "structuredResult",
+        "diagnostics",
+        "exit"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "contract": { "const": "kungfu-buildchain-v4-host-response" },
+        "protocolVersion": { "const": "1.0" },
+        "requestId": { "type": "string", "minLength": 1 },
+        "status": {
+          "enum": ["ok", "unsupported", "failed", "cancelled"]
+        },
+        "host": {
+          "type": "object",
+          "required": ["kind", "implementation", "capabilities"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "type": "string", "minLength": 1 },
+            "implementation": { "type": "string", "minLength": 1 },
+            "capabilities": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "command": { "$ref": "#/$defs/command" },
+        "output": {
+          "type": "object",
+          "required": ["stdout", "stderr"],
+          "additionalProperties": false,
+          "properties": {
+            "stdout": { "$ref": "#/$defs/encodedBytes" },
+            "stderr": { "$ref": "#/$defs/encodedBytes" }
+          }
+        },
+        "structuredResult": true,
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/diagnostic" }
+        },
+        "exit": {
+          "type": "object",
+          "required": ["code", "signal"],
+          "additionalProperties": false,
+          "properties": {
+            "code": { "type": "integer", "minimum": 0, "maximum": 255 },
+            "signal": { "type": ["string", "null"] }
+          }
+        }
+      }
+    }
+  }
+}

package/contracts/v4-partial-mutation-recovery-v1.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schema/v4-partial-mutation-recovery-v1.schema.json",
+  "title": "Buildchain v4 partial provider mutation recovery request",
+  "description": "Closed production evidence contract for deterministic partial provider mutation recovery planning. Provider effects remain outside this pure planner and require the exact authorized plan.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "evaluatedAt",
+    "sourceRoot",
+    "policyRoot",
+    "platformRoot",
+    "qualificationRoot",
+    "maxAttempts",
+    "compensableBoundaryRoots",
+    "stageResume",
+    "activation"
+  ],
+  "properties": {
+    "schema": {
+      "const": "buildchain-v4-partial-mutation-recovery-request/v1"
+    },
+    "evaluatedAt": { "$ref": "#/$defs/clock" },
+    "sourceRoot": { "$ref": "#/$defs/root" },
+    "policyRoot": { "$ref": "#/$defs/root" },
+    "platformRoot": { "$ref": "#/$defs/root" },
+    "qualificationRoot": { "$ref": "#/$defs/root" },
+    "maxAttempts": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "compensableBoundaryRoots": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/root" }
+    },
+    "stageResume": { "$ref": "#/$defs/stageResume" },
+    "activation": { "$ref": "#/$defs/activation" }
+  },
+  "$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" }
+    },
+    "stageDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stageKey", "decision", "reasonCode"],
+      "properties": {
+        "stageKey": { "$ref": "#/$defs/token" },
+        "decision": { "enum": ["reuse", "rebuild", "reject"] },
+        "reasonCode": { "$ref": "#/$defs/token" }
+      }
+    },
+    "stageResume": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "planRoot",
+        "sourceRoot",
+        "policyRoot",
+        "platformRoot",
+        "qualificationRoots",
+        "decisions"
+      ],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-stage-capsule-resume-evidence/v1"
+        },
+        "planRoot": { "$ref": "#/$defs/root" },
+        "sourceRoot": { "$ref": "#/$defs/root" },
+        "policyRoot": { "$ref": "#/$defs/root" },
+        "platformRoot": { "$ref": "#/$defs/root" },
+        "qualificationRoots": { "$ref": "#/$defs/rootSet" },
+        "decisions": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/stageDecision" }
+        }
+      }
+    },
+    "activationStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "stepId",
+        "operationRoot",
+        "phase",
+        "journalRoot",
+        "journalStateRoot",
+        "compensationBoundaryRoot",
+        "attemptCount"
+      ],
+      "properties": {
+        "stepId": { "$ref": "#/$defs/token" },
+        "operationRoot": { "$ref": "#/$defs/root" },
+        "phase": {
+          "enum": [
+            "planned",
+            "intended",
+            "attempting",
+            "observed",
+            "confirmable",
+            "retryable",
+            "confirmed",
+            "rejected",
+            "terminal"
+          ]
+        },
+        "journalRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "journalStateRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "compensationBoundaryRoot": { "$ref": "#/$defs/root" },
+        "attemptCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "activation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "planRoot",
+        "stateRoot",
+        "qualificationRoot",
+        "policyRoot",
+        "steps"
+      ],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-release-activation-recovery-evidence/v1"
+        },
+        "planRoot": { "$ref": "#/$defs/root" },
+        "stateRoot": { "$ref": "#/$defs/root" },
+        "qualificationRoot": { "$ref": "#/$defs/root" },
+        "policyRoot": { "$ref": "#/$defs/root" },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/activationStep" }
+        }
+      }
+    }
+  }
+}

package/contracts/v4-provider-operation-journal-v1.schema.json

@@ -0,0 +1,381 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schema/v4-provider-operation-journal-v1.schema.json",
+  "title": "Buildchain v4 provider operation journal contract suite",
+  "description": "The sole closed schema authority for append-only shadow intent, attempt, rooted observation, confirmation, reconciliation, and deterministic journal state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "identity",
+    "entry",
+    "state",
+    "readbackSample",
+    "readbackFold"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "identity": { "$ref": "#/$defs/identity" },
+    "entry": { "$ref": "#/$defs/entry" },
+    "state": { "$ref": "#/$defs/state" },
+    "readbackSample": { "$ref": "#/$defs/readbackSample" },
+    "readbackFold": { "$ref": "#/$defs/readbackFold" }
+  },
+  "$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]+)*$"
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "identity": {
+      "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" }
+      }
+    },
+    "entryBase": {
+      "type": "object",
+      "required": [
+        "kind",
+        "schema",
+        "sequence",
+        "priorEntryRoot",
+        "operationRoot",
+        "entryRoot"
+      ],
+      "properties": {
+        "kind": { "$ref": "#/$defs/token" },
+        "schema": { "type": "string", "minLength": 1 },
+        "sequence": { "$ref": "#/$defs/sequence" },
+        "priorEntryRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "operationRoot": { "$ref": "#/$defs/root" },
+        "entryRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "intent": {
+      "allOf": [
+        { "$ref": "#/$defs/entryBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "schema",
+            "sequence",
+            "priorEntryRoot",
+            "operation",
+            "operationRoot",
+            "declaredAt",
+            "inputRoot",
+            "entryRoot"
+          ],
+          "properties": {
+            "kind": { "const": "intent" },
+            "schema": { "const": "buildchain-v4-provider-operation-intent/v1" },
+            "sequence": { "const": 0 },
+            "priorEntryRoot": { "type": "null" },
+            "operation": { "$ref": "#/$defs/identity" },
+            "operationRoot": { "$ref": "#/$defs/root" },
+            "declaredAt": { "$ref": "#/$defs/clock" },
+            "inputRoot": { "$ref": "#/$defs/root" },
+            "entryRoot": { "$ref": "#/$defs/root" }
+          }
+        }
+      ]
+    },
+    "attempt": {
+      "allOf": [
+        { "$ref": "#/$defs/entryBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "schema",
+            "sequence",
+            "priorEntryRoot",
+            "operationRoot",
+            "attemptOrdinal",
+            "attemptedAt",
+            "effectRoot",
+            "entryRoot"
+          ],
+          "properties": {
+            "kind": { "const": "attempt" },
+            "schema": {
+              "const": "buildchain-v4-provider-operation-attempt/v1"
+            },
+            "sequence": { "$ref": "#/$defs/sequence" },
+            "priorEntryRoot": { "$ref": "#/$defs/root" },
+            "operationRoot": { "$ref": "#/$defs/root" },
+            "attemptOrdinal": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            },
+            "attemptedAt": { "$ref": "#/$defs/clock" },
+            "effectRoot": { "$ref": "#/$defs/root" },
+            "entryRoot": { "$ref": "#/$defs/root" }
+          }
+        }
+      ]
+    },
+    "observation": {
+      "allOf": [
+        { "$ref": "#/$defs/entryBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "schema",
+            "sequence",
+            "priorEntryRoot",
+            "operationRoot",
+            "attemptRoot",
+            "observedAt",
+            "status",
+            "evidenceRoots",
+            "entryRoot"
+          ],
+          "properties": {
+            "kind": { "const": "observation" },
+            "schema": {
+              "const": "buildchain-v4-provider-operation-observation/v1"
+            },
+            "sequence": { "$ref": "#/$defs/sequence" },
+            "priorEntryRoot": { "$ref": "#/$defs/root" },
+            "operationRoot": { "$ref": "#/$defs/root" },
+            "attemptRoot": { "$ref": "#/$defs/root" },
+            "observedAt": { "$ref": "#/$defs/clock" },
+            "status": { "enum": ["succeeded", "failed", "unknown"] },
+            "evidenceRoots": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "$ref": "#/$defs/root" }
+            },
+            "entryRoot": { "$ref": "#/$defs/root" }
+          }
+        }
+      ]
+    },
+    "confirmation": {
+      "allOf": [
+        { "$ref": "#/$defs/entryBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "schema",
+            "sequence",
+            "priorEntryRoot",
+            "operationRoot",
+            "observationRoot",
+            "authorityRoot",
+            "confirmedAt",
+            "outcome",
+            "entryRoot"
+          ],
+          "properties": {
+            "kind": { "const": "confirmation" },
+            "schema": {
+              "const": "buildchain-v4-provider-operation-confirmation/v1"
+            },
+            "sequence": { "$ref": "#/$defs/sequence" },
+            "priorEntryRoot": { "$ref": "#/$defs/root" },
+            "operationRoot": { "$ref": "#/$defs/root" },
+            "observationRoot": { "$ref": "#/$defs/root" },
+            "authorityRoot": { "$ref": "#/$defs/root" },
+            "confirmedAt": { "$ref": "#/$defs/clock" },
+            "outcome": { "enum": ["confirmed", "rejected"] },
+            "entryRoot": { "$ref": "#/$defs/root" }
+          }
+        }
+      ]
+    },
+    "reconciliation": {
+      "allOf": [
+        { "$ref": "#/$defs/entryBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "schema",
+            "sequence",
+            "priorEntryRoot",
+            "operationRoot",
+            "observationRoot",
+            "authorityRoot",
+            "reconciledAt",
+            "disposition",
+            "entryRoot"
+          ],
+          "properties": {
+            "kind": { "const": "reconciliation" },
+            "schema": {
+              "const": "buildchain-v4-provider-operation-reconciliation/v1"
+            },
+            "sequence": { "$ref": "#/$defs/sequence" },
+            "priorEntryRoot": { "$ref": "#/$defs/root" },
+            "operationRoot": { "$ref": "#/$defs/root" },
+            "observationRoot": { "$ref": "#/$defs/root" },
+            "authorityRoot": { "$ref": "#/$defs/root" },
+            "reconciledAt": { "$ref": "#/$defs/clock" },
+            "disposition": { "enum": ["retry", "confirm", "terminal"] },
+            "entryRoot": { "$ref": "#/$defs/root" }
+          }
+        }
+      ]
+    },
+    "entry": {
+      "oneOf": [
+        { "$ref": "#/$defs/intent" },
+        { "$ref": "#/$defs/attempt" },
+        { "$ref": "#/$defs/observation" },
+        { "$ref": "#/$defs/confirmation" },
+        { "$ref": "#/$defs/reconciliation" }
+      ]
+    },
+    "readbackSample": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "operationRoot",
+        "attemptRoot",
+        "state",
+        "observedTargetRoot",
+        "evidenceRoots",
+        "sampleRoot"
+      ],
+      "properties": {
+        "schema": { "const": "buildchain-v4-provider-readback-sample/v1" },
+        "operationRoot": { "$ref": "#/$defs/root" },
+        "attemptRoot": { "$ref": "#/$defs/root" },
+        "state": {
+          "enum": ["not-found", "eventually-visible", "already-applied"]
+        },
+        "observedTargetRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "evidenceRoots": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/root" }
+        },
+        "sampleRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "readbackFold": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "classification",
+        "readbackRoots",
+        "observation",
+        "projectionRoot"
+      ],
+      "properties": {
+        "schema": { "const": "buildchain-v4-provider-readback-fold/v1" },
+        "classification": {
+          "enum": ["not-found", "eventually-visible", "already-applied"]
+        },
+        "readbackRoots": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/root" }
+        },
+        "observation": { "$ref": "#/$defs/observation" },
+        "projectionRoot": { "$ref": "#/$defs/root" }
+      }
+    },
+    "state": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "operationRoot",
+        "phase",
+        "entryCount",
+        "attemptCount",
+        "lastEntryRoot",
+        "activeAttemptRoot",
+        "lastObservationRoot",
+        "confirmationRoot",
+        "reconciliationRoot"
+      ],
+      "properties": {
+        "schema": {
+          "const": "buildchain-v4-provider-operation-journal-state/v1"
+        },
+        "operationRoot": { "$ref": "#/$defs/root" },
+        "phase": {
+          "enum": [
+            "intended",
+            "attempting",
+            "observed",
+            "retryable",
+            "confirmable",
+            "confirmed",
+            "rejected",
+            "terminal"
+          ]
+        },
+        "entryCount": { "$ref": "#/$defs/sequence" },
+        "attemptCount": { "$ref": "#/$defs/sequence" },
+        "lastEntryRoot": { "$ref": "#/$defs/root" },
+        "activeAttemptRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "lastObservationRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "confirmationRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        },
+        "reconciliationRoot": {
+          "oneOf": [{ "$ref": "#/$defs/root" }, { "type": "null" }]
+        }
+      }
+    }
+  }
+}