Closeout

Draft 0.1

Schemas

Draft 0.1 uses JSON Schema draft 2020-12. Unknown fields are errors. A policy, an evidence record, and a decision each have a schema.

Closeout policy document, draft 0.1

A public policy file. specVersion is 0.1. Items are command or review, and the only gate is beforePR.

urn:closeout:policy:0.1 

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:closeout:policy:0.1",
  "title": "Closeout policy document, draft 0.1",
  "type": "object",
  "additionalProperties": false,
  "required": ["specVersion"],
  "properties": {
    "specVersion": { "const": "0.1" },
    "description": { "type": "string", "minLength": 1, "maxLength": 500 },
    "imports": {
      "type": "array",
      "maxItems": 64,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["path", "as"],
        "properties": {
          "path": { "type": "string", "minLength": 1, "maxLength": 256 },
          "as": { "$ref": "#/$defs/slug" }
        }
      }
    },
    "items": {
      "type": "array",
      "maxItems": 128,
      "items": { "$ref": "#/$defs/item" }
    }
  },
  "$defs": {
    "slug": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
    },
    "item": {
      "oneOf": [{ "$ref": "#/$defs/command" }, { "$ref": "#/$defs/review" }]
    },
    "command": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "gate", "exec", "timeoutSeconds"],
      "properties": {
        "id": { "$ref": "#/$defs/slug" },
        "kind": { "const": "command" },
        "gate": { "const": "beforePR" },
        "exec": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": { "type": "string", "minLength": 1, "maxLength": 4096 }
        },
        "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }
      }
    },
    "review": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "gate", "skill", "independence", "failOn"],
      "properties": {
        "id": { "$ref": "#/$defs/slug" },
        "kind": { "const": "review" },
        "gate": { "const": "beforePR" },
        "skill": { "type": "string", "minLength": 1, "maxLength": 256 },
        "independence": {
          "type": "object",
          "additionalProperties": false,
          "required": ["differentSession", "differentModel"],
          "properties": {
            "differentSession": { "type": "boolean" },
            "differentModel": { "type": "boolean" }
          }
        },
        "failOn": { "enum": ["P0", "P1", "P2", "P3"] }
      }
    }
  }
}

Closeout evidence record, draft 0.1

One evidence record. A command record carries the argv, the exit, and the producer. A review record carries findings and does not carry an outcome.

urn:closeout:evidence:0.1 

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:closeout:evidence:0.1",
  "title": "Closeout evidence record, draft 0.1",
  "oneOf": [{ "$ref": "#/$defs/command" }, { "$ref": "#/$defs/review" }],
  "$defs": {
    "sha": { "type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$" },
    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
    "attempt": { "type": "integer", "minimum": 1, "maximum": 100000 },
    "artifact": {
      "type": "object",
      "additionalProperties": false,
      "required": ["path", "sha256"],
      "properties": {
        "path": { "type": "string", "minLength": 1, "maxLength": 512 },
        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
      }
    },
    "identity": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "version"],
      "properties": {
        "name": { "type": "string", "minLength": 1, "maxLength": 128 },
        "version": { "type": "string", "minLength": 1, "maxLength": 64 }
      }
    },
    "command": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "specVersion",
        "recordType",
        "itemId",
        "base",
        "head",
        "policyDigest",
        "attempt",
        "evaluator",
        "producer",
        "exec",
        "artifacts"
      ],
      "properties": {
        "specVersion": { "const": "0.1" },
        "recordType": { "const": "command" },
        "itemId": { "type": "string", "minLength": 1, "maxLength": 256 },
        "base": { "$ref": "#/$defs/sha" },
        "head": { "$ref": "#/$defs/sha" },
        "policyDigest": { "$ref": "#/$defs/digest" },
        "attempt": { "$ref": "#/$defs/attempt" },
        "evaluator": { "$ref": "#/$defs/identity" },
        "producer": { "$ref": "#/$defs/identity" },
        "exec": {
          "type": "object",
          "additionalProperties": false,
          "required": ["argv", "exitCode", "timedOut", "dirty", "headMoved", "durationMs", "truncated"],
          "properties": {
            "argv": {
              "type": "array",
              "minItems": 1,
              "maxItems": 32,
              "items": { "type": "string", "minLength": 1 }
            },
            "exitCode": { "type": ["integer", "null"] },
            "timedOut": { "type": "boolean" },
            "dirty": { "type": "boolean" },
            "headMoved": { "type": "boolean" },
            "durationMs": { "type": "integer", "minimum": 0 },
            "truncated": { "type": "boolean" }
          }
        },
        "artifacts": {
          "type": "array",
          "maxItems": 16,
          "items": { "$ref": "#/$defs/artifact" }
        }
      }
    },
    "review": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "specVersion",
        "recordType",
        "itemId",
        "base",
        "head",
        "policyDigest",
        "attempt",
        "evaluator",
        "producer",
        "findings",
        "artifacts"
      ],
      "properties": {
        "specVersion": { "const": "0.1" },
        "recordType": { "const": "review" },
        "itemId": { "type": "string", "minLength": 1, "maxLength": 256 },
        "base": { "$ref": "#/$defs/sha" },
        "head": { "$ref": "#/$defs/sha" },
        "policyDigest": { "$ref": "#/$defs/digest" },
        "attempt": { "$ref": "#/$defs/attempt" },
        "evaluator": { "$ref": "#/$defs/identity" },
        "producer": {
          "type": "object",
          "additionalProperties": false,
          "required": ["session", "model", "provider"],
          "properties": {
            "session": { "type": "string", "maxLength": 256 },
            "model": { "type": "string", "maxLength": 256 },
            "provider": { "type": "string", "maxLength": 256 }
          }
        },
        "findings": {
          "type": "array",
          "maxItems": 200,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["severity", "location", "explanation", "evidence"],
            "properties": {
              "severity": { "enum": ["P0", "P1", "P2", "P3"] },
              "location": { "type": "string", "minLength": 1, "maxLength": 512 },
              "explanation": { "type": "string", "minLength": 1, "maxLength": 8000 },
              "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 }
            }
          }
        },
        "artifacts": {
          "type": "array",
          "maxItems": 16,
          "items": { "$ref": "#/$defs/artifact" }
        }
      }
    }
  }
}

Closeout decision, draft 0.1

The acceptance decision for one gate, one base, and one head. The decision is accepted, rejected, or blocked.

urn:closeout:decision:0.1 

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:closeout:decision:0.1",
  "title": "Closeout decision, draft 0.1",
  "type": "object",
  "additionalProperties": false,
  "required": ["specVersion", "decision", "gate", "base", "head", "candidate", "policy", "items", "warnings"],
  "properties": {
    "specVersion": { "const": "0.1" },
    "decision": { "enum": ["accepted", "rejected", "blocked"] },
    "gate": { "const": "beforePR" },
    "base": { "type": "string" },
    "head": { "type": "string" },
    "message": { "type": "string", "maxLength": 4000 },
    "candidate": {
      "type": "object",
      "additionalProperties": false,
      "required": ["session", "model", "provider"],
      "properties": {
        "session": { "type": "string", "maxLength": 256 },
        "model": { "type": "string", "maxLength": 256 },
        "provider": { "type": "string", "maxLength": 256 }
      }
    },
    "policy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["path", "legacy", "digest", "absent"],
      "properties": {
        "path": { "type": ["string", "null"] },
        "legacy": { "type": "boolean" },
        "digest": { "type": ["string", "null"] },
        "absent": { "type": "boolean" }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "kind", "state", "message"],
        "properties": {
          "id": { "type": "string" },
          "kind": { "type": "string" },
          "state": {
            "enum": ["passed", "failed", "missing", "stale", "unsupported", "independence", "untrusted", "invalid"]
          },
          "message": { "type": "string" },
          "attempt": { "type": "integer", "minimum": 1 }
        }
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  }
}