@intentius/chant 0.124.26 → 0.124.28

package/dist/workspace/releases.schema.json

@@ -0,0 +1,391 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json",
+  "title": "chant release list output",
+  "description": "What `chant release list --json` prints (#4026, ws-104): every release of one member, each the compiled output of one green commit, with its artifact digests, one target per environment, its cuts and the environments that run it. It reads the local chant/lifecycle branch and never fetches. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.28 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0, with or without releases.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "releases",
+        "reason"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The workspace member read, its path of names joined with / when nested, or null for a project outside a workspace (the flat ledger layout)."
+        },
+        "releases": {
+          "type": "array",
+          "description": "Newest cut first. A release stored with no cut comes last.",
+          "items": {
+            "$ref": "#/$defs/release"
+          }
+        },
+        "reason": {
+          "description": "Null when everything was read. ledger-malformed when some release files or cut lines could not be read; the rest are listed.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code",
+                "message"
+              ],
+              "properties": {
+                "code": {
+                  "enum": [
+                    "ledger-malformed"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "releaseDigest",
+        "label",
+        "member",
+        "commit",
+        "artifactDigests",
+        "targets",
+        "cuts",
+        "environments"
+      ],
+      "properties": {
+        "releaseDigest": {
+          "type": "string",
+          "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$",
+          "description": "computePlanDigest(\"release\", subject) over member, commit, artifactDigests, and each target's env, templates and the name and value of each param. The file is _releases/<releaseDigest>.json on chant/lifecycle, with : written as _."
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The release's label, from its cuts, or null. A label names one release in a member and a release takes at most one label."
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full sha of the green commit the release was cut from."
+        },
+        "artifactDigests": {
+          "type": "array",
+          "description": "Each image and asset built once from the commit, sorted by component, then path. A config-only release carries the previous release's entries.",
+          "items": {
+            "type": "object",
+            "required": [
+              "component",
+              "kind",
+              "path",
+              "digest"
+            ],
+            "properties": {
+              "component": {
+                "type": "string"
+              },
+              "kind": {
+                "enum": [
+                  "image",
+                  "asset"
+                ]
+              },
+              "path": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "targets": {
+          "type": "array",
+          "description": "One per environment the member declares, sorted by env.",
+          "items": {
+            "$ref": "#/$defs/target"
+          }
+        },
+        "cuts": {
+          "type": "array",
+          "description": "Each cut of the release, oldest first.",
+          "items": {
+            "$ref": "#/$defs/cut"
+          }
+        },
+        "environments": {
+          "type": "array",
+          "description": "The environments that run the release, sorted by env: in each, the components whose latest deploy record names this release in releaseDigest. A promote with --release writes that field. An environment can run components of several releases.",
+          "items": {
+            "type": "object",
+            "required": [
+              "env",
+              "components"
+            ],
+            "properties": {
+              "env": {
+                "type": "string"
+              },
+              "components": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "required": [
+        "env",
+        "templates",
+        "params"
+      ],
+      "properties": {
+        "env": {
+          "type": "string"
+        },
+        "templates": {
+          "type": "array",
+          "description": "The files the environment's deploys read, compiled for it, sorted by component, then path.",
+          "items": {
+            "type": "object",
+            "required": [
+              "component",
+              "path",
+              "digest"
+            ],
+            "properties": {
+              "component": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The component whose deploy reads it, or null for a project with no components."
+              },
+              "path": {
+                "type": "string",
+                "description": "The path the deploy step names, relative to the member's directory."
+              },
+              "digest": {
+                "type": "string",
+                "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$",
+                "description": "sha256 of the file's bytes."
+              }
+            }
+          }
+        },
+        "params": {
+          "type": "array",
+          "description": "The resolved build parameters the environment was compiled with, sorted by name. source is outside the release digest.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "value",
+              "source"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "value": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "source": {
+                "type": "string",
+                "description": "cli, params-file, env or default."
+              }
+            }
+          }
+        }
+      }
+    },
+    "cut": {
+      "type": "object",
+      "required": [
+        "label",
+        "actor",
+        "timestamp",
+        "runOrigin",
+        "signature"
+      ],
+      "properties": {
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "actor": {
+          "type": "string"
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "ISO 8601."
+        },
+        "runOrigin": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge"
+              ],
+              "properties": {
+                "forge": {
+                  "enum": [
+                    "github",
+                    "gitlab",
+                    "op",
+                    "local"
+                  ]
+                },
+                "repo": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The CI run the cut ran in: the forge (github for GitHub and Forgejo, gitlab), the repo or project, and a link to the run. Null outside CI."
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added by #4031, written by chant 0.124.28 and newer. The cut's armored ssh signature (ssh-keygen -Y sign, namespace chant-release) by the actor's key, over the release digest, the label (empty for none), the actor and the timestamp, joined by LF with no final newline. Null for an unsigned cut. A reader checks it against .chant/allowed_signers at base; signatureCheck is chant's own check."
+        },
+        "signatureCheck": {
+          "type": "object",
+          "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. Whether signature verifies for actor against the signers file at base and, when the declaration at base names a release gate in identity.gates with a class, whether the role grants in .chant/trust.json at base put actor in it. Judged on every read.",
+          "required": [
+            "status",
+            "key",
+            "reason"
+          ],
+          "properties": {
+            "status": {
+              "enum": [
+                "verified",
+                "unsigned",
+                "unverified"
+              ],
+              "description": "verified: the signature verifies, and the actor is in the release gate's class when it names one. unsigned: the cut has no signature. unverified: it has one that does not count, and reason says why."
+            },
+            "key": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The fingerprint (SHA256:...) of the key in the signature, or null for an unsigned cut or a signature that can't be read. Reported, never trusted."
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "ledger-unreadable"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/workspace/run-event.schema.json

@@ -0,0 +1,288 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/run-event/v1/run-event.schema.json",
+  "title": "chant run event",
+  "description": "One event of a run's stream (#4019, behold #678): one JSON object per line, written by writeRunEvent and createRunEventWriter in src/run-event.ts. It covers Op runs, component runs and pipeline runs alike. Every event names the run, what it ran, the commit it built from and the runtime it ran on, so a reader shows a run the same way wherever it happened. A run's stream opens with run-start and ends with run-settle, whose status is the run's verdict; seq counts the events from 0. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The status sets are closed. Contract version 1 of this document is written by chant 0.124.28 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    { "$ref": "#/$defs/run-start" },
+    { "$ref": "#/$defs/run-settle" },
+    { "$ref": "#/$defs/wave-start" },
+    { "$ref": "#/$defs/wave-settle" },
+    { "$ref": "#/$defs/component-start" },
+    { "$ref": "#/$defs/component-settle" },
+    { "$ref": "#/$defs/phase-start" },
+    { "$ref": "#/$defs/phase-settle" },
+    { "$ref": "#/$defs/step-start" },
+    { "$ref": "#/$defs/step-settle" },
+    { "$ref": "#/$defs/gate-waiting" },
+    { "$ref": "#/$defs/gate-resolved" }
+  ],
+  "$defs": {
+    "envelope": {
+      "type": "object",
+      "description": "What every event carries.",
+      "required": ["$schema", "contract", "chant", "seq", "at", "type", "runId", "kind", "name", "gitSha", "runtime", "runOrigin"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/run-event/v1/run-event.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string", "description": "The version of the chant that wrote the event." },
+        "seq": { "type": "integer", "minimum": 0, "description": "The event's place in its run's stream: 0 for run-start, one more for each event after it." },
+        "at": { "type": "string", "description": "When the event happened, ISO-8601." },
+        "type": { "type": "string" },
+        "runId": { "type": "string", "minLength": 1, "description": "The run's own id: an Op run's id, a component run's id (the id its release records carry, the CI run id in CI, else one minted locally), or the CI run id for a pipeline run. runOrigin says where it ran, which for an Op run in CI is the CI run, not the id space of runId." },
+        "kind": { "enum": ["op", "component", "pipeline"], "description": "What ran: an Op, a component selection (chant run --components), or a CI pipeline." },
+        "name": { "type": "string", "description": "The Op's name, the component selection as given, or the pipeline's name." },
+        "gitSha": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The commit the run built from, the same field a release record carries. Null when the run did not start in a git checkout."
+        },
+        "runtime": {
+          "enum": ["local", "steward", "ci"],
+          "description": "Where the run happened: in the process that started it, on a steward, or in a forge's CI."
+        },
+        "runOrigin": { "$ref": "#/$defs/runOrigin" }
+      }
+    },
+    "runOrigin": {
+      "type": "object",
+      "description": "Where the run ran and how to reach it: RunOrigin from lifecycle/release-ledger.ts, the shape a release record's runOrigin has. For an Op run in CI it locates the CI run, as the Op's run record does (#4020), while runId stays the Op run's own id.",
+      "required": ["forge"],
+      "properties": {
+        "forge": {
+          "enum": ["github", "gitlab", "op", "local"],
+          "description": "github: a GitHub Actions run, also the spelling Forgejo Actions uses. gitlab: a CI pipeline. op: a steward's run, named by its Op run id. local: a run on the machine that started it, outside CI."
+        },
+        "repo": { "type": "string", "description": "The repository or project slug on the forge, when the environment named one." },
+        "url": { "type": "string", "description": "A link to the run, when the environment gave enough to build one." }
+      }
+    },
+    "settleStatus": {
+      "enum": ["ok", "failed", "gated", "waiting"],
+      "description": "How a run, wave, component or phase settled. gated: it stopped at a gate nobody has approved. waiting: it stopped at a decision point nobody has answered. Neither is a failure."
+    },
+    "stepIndex": { "type": "integer", "minimum": 0, "description": "The step's place in its phase as authored, counting from 0, so two steps of one phase that share a name stay apart. Optional, added within contract 1 by chant 0.124.28 (#4041). A writer leaves it out for a step it has no authored place for, and a reader without it pairs a step-start with its step-settle by component, phase and step in stream order." },
+    "component": {
+      "type": ["string", "null"],
+      "description": "The component whose composition the phase or step belongs to in a component run, and null in an Op or pipeline run."
+    },
+    "run-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "The run is about to start.",
+          "required": ["type", "waves"],
+          "properties": {
+            "type": { "const": "run-start" },
+            "waves": {
+              "type": ["array", "null"],
+              "items": { "type": "array", "items": { "type": "string" } },
+              "description": "In a component run, the waves of components the run will attempt, in order; wave numbers in later events count from 1 into this list. Null in an Op or pipeline run."
+            }
+          }
+        }
+      ]
+    },
+    "run-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "The run settled. The last event of the stream, and its verdict.",
+          "required": ["type", "status", "durationMs"],
+          "properties": {
+            "type": { "const": "run-settle" },
+            "status": { "$ref": "#/$defs/settleStatus" },
+            "durationMs": { "type": ["integer", "null"], "minimum": 0, "description": "From run-start to now, or null when the writer did not time it." },
+            "error": { "type": "string", "description": "With status failed, what failed, when the writer knows." }
+          }
+        }
+      ]
+    },
+    "wave-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A wave of a component run is about to start. Its components may run at the same time.",
+          "required": ["type", "wave", "components"],
+          "properties": {
+            "type": { "const": "wave-start" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "components": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      ]
+    },
+    "wave-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A wave settled. failed if any component in it failed, which stops the run before the next wave.",
+          "required": ["type", "wave", "status"],
+          "properties": {
+            "type": { "const": "wave-settle" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "status": { "$ref": "#/$defs/settleStatus" }
+          }
+        }
+      ]
+    },
+    "component-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A component in a wave is about to start its deploy composition.",
+          "required": ["type", "wave", "component"],
+          "properties": {
+            "type": { "const": "component-start" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "component": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "component-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A component's composition settled, after any rollback the run did for it.",
+          "required": ["type", "wave", "component", "status"],
+          "properties": {
+            "type": { "const": "component-settle" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "component": { "type": "string" },
+            "status": { "$ref": "#/$defs/settleStatus" }
+          }
+        }
+      ]
+    },
+    "phase-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A phase is about to run its steps: an Op's phase, a component composition's phase, or a pipeline's stage.",
+          "required": ["type", "component", "phase"],
+          "properties": {
+            "type": { "const": "phase-start" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "phase-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A phase settled: ok when every step in it settled ok, skipped or cached.",
+          "required": ["type", "component", "phase", "status"],
+          "properties": {
+            "type": { "const": "phase-settle" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "status": { "$ref": "#/$defs/settleStatus" }
+          }
+        }
+      ]
+    },
+    "step-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A step is about to run: an Op or composition step, or a pipeline's job. A step that never started, such as one an earlier failure stopped, has a step-settle and no step-start.",
+          "required": ["type", "component", "phase", "step"],
+          "properties": {
+            "type": { "const": "step-start" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string", "description": "The step's activity, gate:<name> for a gate, effect:<name> for an effect, or the job's name." },
+            "index": { "$ref": "#/$defs/stepIndex" }
+          }
+        }
+      ]
+    },
+    "step-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A step settled.",
+          "required": ["type", "component", "phase", "step", "status", "durationMs"],
+          "properties": {
+            "type": { "const": "step-settle" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string" },
+            "index": { "$ref": "#/$defs/stepIndex" },
+            "status": {
+              "enum": ["ok", "failed", "skipped", "cached", "gated", "waiting"],
+              "description": "ok: it ran and succeeded. failed: it ran and failed. skipped: it did not run, and skip says why. cached: a cache hit stood in for running it (#4015). gated: it stopped the run at a gate nobody has approved. waiting: it stopped the run at a decision point nobody has answered."
+            },
+            "skip": {
+              "enum": ["receipt", "resumed", "refused", "not-run", null],
+              "description": "With status skipped. receipt: the effect's receipt matched, so it had already applied. resumed: the run resumed at a later gate and carried this step's output from an earlier run. refused: it declined to go on, and message says why. not-run: an earlier step failed or stopped the run. Null when the writer does not know."
+            },
+            "durationMs": { "type": ["integer", "null"], "minimum": 0, "description": "How long it ran, or null when the writer did not time it." },
+            "error": { "type": "string", "description": "With status failed, what failed." },
+            "message": { "type": "string", "description": "Why a step skipped, gated or waited, for a person." }
+          }
+        }
+      ]
+    },
+    "gate-waiting": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "The run stopped and waits on a person: a gate nobody has approved, or a decision point nobody has answered. The step settles gated or waiting next.",
+          "required": ["type", "component", "phase", "step", "op", "gate", "point"],
+          "properties": {
+            "type": { "const": "gate-waiting" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string" },
+            "index": { "$ref": "#/$defs/stepIndex" },
+            "op": { "type": "string", "description": "The op the gate is recorded under, which chant approve takes. It differs from name when a step's command stopped at a gate of its own." },
+            "gate": { "type": ["string", "null"], "description": "The gate's name, or null when the step waits on a decision point alone." },
+            "point": { "type": ["string", "null"], "description": "The answer record id of the open question, which points answer takes, or null." },
+            "message": { "type": "string", "description": "Why the gate did not pass, such as an approval for a different plan." }
+          }
+        }
+      ]
+    },
+    "gate-resolved": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A gate the run reached was approved, so its step goes on.",
+          "required": ["type", "component", "phase", "step", "op", "gate", "resolvedBy", "resolvedAt", "via"],
+          "properties": {
+            "type": { "const": "gate-resolved" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string" },
+            "index": { "$ref": "#/$defs/stepIndex" },
+            "op": { "type": "string" },
+            "gate": { "type": "string" },
+            "resolvedBy": { "type": "string", "description": "Who approved it." },
+            "resolvedAt": { "type": "string", "description": "When the approval was recorded, ISO-8601." },
+            "via": {
+              "enum": ["quorum", "policy", "point", "alias", "empty", null],
+              "description": "How the approval passed when it was more than one person's approval of this gate: a quorum, a policy permit, a decision point's answer, or an approval recorded under one of the gate's aliases. empty (added within contract 1 by #4045, chant 0.124.28 and newer): a release gate passed over an empty change set with no approval, on the resolution the promote wrote, whose resolvedBy is the actor running it."
+            },
+            "url": { "type": "string", "description": "Where the approval was made, when known." }
+          }
+        }
+      ]
+    }
+  }
+}