@intentius/chant 0.124.27 → 0.124.29

package/dist/workspace/status.schema.json

@@ -123,6 +123,10 @@
           "type": "array",
           "items": { "$ref": "#/$defs/acceptance" }
         },
+        "overlap": {
+          "description": "Added in contract 1 by #4025, written by chant 0.124.29 and newer; absent from older output, so a reader treats a missing field as unknown. Overlap between in-flight work items: a work item (a current record of a declared work kind) is in flight unless it implements at least one decision and every one is confirmed (in one of its kind's closed states and superseded by nothing, as featureFlags reads it). Its commits are the ones linked to it as #4029 defines linked (a Chant-Record: <work kind>:<id> trailer, or a Chant-Lease trailer that resolves to it), read from every local and remote-tracking branch and HEAD, the chant/ ledger branches left out, merges skipped, and never fetched. Two items overlap when their commits touch the same file, or when one entry of a change set a pending or approved gate binds is attributed to both: an entry is attributed to an item when a commit linked to the item changed the entry's source file (recorded on the stored change set) and that commit is in the history the change set was planned from. A report only: nothing is locked or refused. Null when the workspace declares no work kind, or the work records or history can't be read.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/overlap" }]
+        },
         "summary": {
           "type": "object",
           "required": ["members", "released", "unreadable", "differing"],
@@ -228,9 +232,135 @@
               "message": { "type": "string" }
             }
           }
+        },
+        "promotionOrder": {
+          "description": "The member's promotion order (#4030): the literal entries of the environments array in its chant.config.ts, in order, with a pattern entry such as pr-* left out. A release moves from each step to the next, and components promote --to defaults --from to the step before. Empty when the config declares no environments, and null when it could not be read. canary is declared and shown only; no chant command acts on it yet. Optional: written from chant 0.124.28, absent from older output.",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "required": ["name", "canary"],
+            "properties": {
+              "name": { "type": "string" },
+              "canary": { "type": "boolean", "description": "True when the entry sets canary: true." }
+            }
+          }
+        },
+        "releaseCuts": {
+          "description": "The member's release cuts (#4026, ws-104), oldest first, from _releases/cuts.jsonl on the local chant/lifecycle, each with whether its signature verifies (#4031). Empty when none is cut, null when the cuts could not be read. Optional: written from chant 0.124.28, absent from older output.",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "required": ["releaseDigest", "label", "commit", "actor", "timestamp", "signature", "signatureCheck"],
+            "properties": {
+              "releaseDigest": { "type": "string", "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$" },
+              "label": { "type": ["string", "null"] },
+              "commit": { "type": ["string", "null"], "description": "The release's commit, or null when its release file can't be read." },
+              "actor": { "type": "string", "description": "Who cut it." },
+              "timestamp": { "type": "string", "description": "ISO 8601." },
+              "signature": { "type": ["string", "null"], "description": "The cut's armored ssh signature in the chant-release namespace over the release digest, the label (empty for none), the actor and the timestamp, joined by LF. Null for an unsigned cut." },
+              "signatureCheck": {
+                "type": "object",
+                "description": "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 .chant/trust.json at base puts actor in it. Judged on every read.",
+                "required": ["status", "key", "reason"],
+                "properties": {
+                  "status": { "enum": ["verified", "unsigned", "unverified"] },
+                  "key": { "type": ["string", "null"], "description": "The fingerprint of the key in the signature. Reported, never trusted." },
+                  "reason": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "featureFlags": {
+          "description": "The member's feature flags (#4024): each record of a declared flag kind whose member field names this member, sorted by id. A flag is a workspace record the member's build reads as one build-time parameter, with chant build --env <env>; its value in an environment is recorded on the build, and on a release's target, as a param whose source is flag:<id>. Named featureFlags because a release record's flags already holds legacy-digest. Empty when no flag names the member, and null when the flag records could not be read. Optional: written from chant 0.124.29, absent from older output.",
+          "type": ["array", "null"],
+          "items": { "$ref": "#/$defs/featureFlag" }
         }
       }
     },
+    "overlap": {
+      "type": "object",
+      "required": ["items", "pairs", "changeSets", "unattributed"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "description": "Each in-flight work item with at least one linked commit, sorted by item.",
+          "items": {
+            "type": "object",
+            "required": ["item", "path", "state", "commits"],
+            "properties": {
+              "item": { "type": "string", "description": "<work kind>:<id>, as a Chant-Record trailer names it." },
+              "path": { "type": "string", "description": "The work record file, from the repository root." },
+              "state": { "type": ["string", "null"] },
+              "commits": { "type": "array", "items": { "type": "string" }, "description": "The commits linked to the item, newest first." }
+            }
+          }
+        },
+        "pairs": {
+          "type": "array",
+          "description": "Each pair of items that share a file or a change-set entry, sorted by the first item and then the second. Empty when nothing overlaps.",
+          "items": {
+            "type": "object",
+            "required": ["items", "files", "addresses"],
+            "properties": {
+              "items": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2, "description": "The two items, in sorted order." },
+              "files": { "type": "array", "items": { "type": "string" }, "description": "The paths, from the repository root, that both items' linked commits add, change or delete, sorted. A rename counts as a delete and an add." },
+              "addresses": {
+                "type": "array",
+                "description": "The change-set entries attributed to both items, by change set, member and address.",
+                "items": {
+                  "type": "object",
+                  "required": ["changeSet", "ledgerMember", "member", "address", "node", "source"],
+                  "properties": {
+                    "changeSet": { "type": "string", "description": "The change set's digest, for chant change-set show." },
+                    "ledgerMember": { "type": ["string", "null"], "description": "The workspace member whose ledger stores the change set, or null for the flat ledger." },
+                    "member": { "type": "string", "description": "The entry's change-set member." },
+                    "address": { "type": "string", "description": "The entry's planner address." },
+                    "node": { "type": ["string", "null"], "description": "The entry's graph node." },
+                    "source": { "type": "string", "description": "The entry's source file, from the repository root, that both items' commits changed." }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "changeSets": { "type": "array", "items": { "type": "string" }, "description": "The digests of the stored change sets read: those a pending or approved gate binds, sorted." },
+        "unattributed": { "type": "integer", "minimum": 0, "description": "Entries of those change sets with no source (stored by a chant before 0.124.29, or mapped onto no node with a source location), so attributed to no item." }
+      }
+    },
+    "featureFlag": {
+      "type": "object",
+      "required": ["id", "param", "owner", "values", "work", "implements", "stale", "kind", "path"],
+      "properties": {
+        "id": { "type": "string", "description": "The flag's name, its record's id." },
+        "param": { "type": "string", "description": "The build parameter of the member the flag sets: a key of buildParams in its chant.config.ts." },
+        "owner": { "type": "string", "description": "Who owns the flag, and removes it when its work is settled." },
+        "values": {
+          "type": "object",
+          "description": "The flag's value per environment, as the record writes it. An environment it leaves out builds with the parameter's declared default.",
+          "additionalProperties": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }] }
+        },
+        "work": {
+          "description": "The work item the flag hides, with that item's state, which is null when no record of the flag kind's work kind has the id. Null when the record names none.",
+          "oneOf": [
+            { "type": "null" },
+            { "type": "object", "required": ["id", "state"], "properties": { "id": { "type": "string" }, "state": { "type": ["string", "null"] } } }
+          ]
+        },
+        "implements": {
+          "type": "array",
+          "description": "Each decision the work item implements, with its state, and confirmed: true when the decision is in one of its kind's closed states and nothing supersedes it.",
+          "items": {
+            "type": "object",
+            "required": ["id", "state", "confirmed"],
+            "properties": { "id": { "type": "string" }, "state": { "type": ["string", "null"] }, "confirmed": { "type": "boolean" } }
+          }
+        },
+        "stale": { "type": "boolean", "description": "True when the work item implements at least one decision and every one is confirmed: the flag is due for removal, and chant workspace check reports it (WSP118)." },
+        "kind": { "type": "string", "description": "The flag kind file, from the workspace root." },
+        "path": { "type": "string", "description": "The flag record file, from the workspace root." }
+      }
+    },
     "stewardForm": { "enum": ["local", "fountain"] },
     "steward": {
       "type": "object",
@@ -313,6 +443,17 @@
                       "status": { "enum": ["ok", "fail", "gated", "waiting"], "description": "waiting: an activity asked a decision point that is still open (#2749), and the run stopped there." },
                       "started": { "type": "string" },
                       "ended": { "type": "string" },
+                      "gitSha": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The commit the run built from. Absent on a record written by an older chant, and when the run knew no commit." },
+                      "runOrigin": {
+                        "type": "object",
+                        "required": ["forge"],
+                        "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The CI run the Op ran in, the shape a release's runOrigin has: the forge (github for GitHub and Forgejo, gitlab), the repo or project, and a link to the run. Absent outside CI.",
+                        "properties": {
+                          "forge": { "enum": ["github", "gitlab", "op", "local"] },
+                          "repo": { "type": "string" },
+                          "url": { "type": "string" }
+                        }
+                      },
                       "gate": {
                         "oneOf": [
                           { "type": "null" },
@@ -825,9 +966,14 @@
         "planDigest": { "type": ["string", "null"], "description": "The plan the run reached the gate with (#2300), or null for a gate that binds no plan. An approval counts only for this plan." },
         "state": {
           "enum": ["pending", "approved", "expired", "superseded"],
-          "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count. pending: none of these."
+          "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count; or, on a release gate that is not expired, its release was cut from a revoked commit (#4033, ws-105), so chant approve refuses it with release-revoked and revoked is set. pending: none of these."
         },
         "recordedAt": { "type": "string", "description": "When the run recorded the pending fact." },
+        "gitSha": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The commit the run reached the gate at, from the pending fact. Absent on a fact recorded by an older chant, and when the run knew no commit. It joins the gate to a release's gitSha and to a run's." },
+        "runId": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The run that reached the gate: an Op run id, or the CI run id for a component gate that ran in CI. Absent when the run had none." },
+        "changeSet": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4022, written by chant 0.124.28 and newer. The change set the gate binds: planDigest, when a change-set document is stored under it in the member's _change-sets/ on chant/lifecycle, as a pull-request gate's apply and a release gate (#4045) store it. chant change-set show <changeSet> --json prints it, each entry with its graph node. Absent when none is stored, as for a component gate, which binds a lifecycle-plan digest." },
+        "releaseDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4045, written by chant 0.124.28 and newer. The release the gate binds, from the pending fact: set on a release gate, the gate chant components promote --release passes for an environment, whose component is the op release. An approval counts toward it only when it was recorded for this release, environment and planDigest. Absent on every other gate." },
+        "revoked": { "$ref": "#/$defs/revocation", "description": "Added in contract 1 by #4033 (ws-105), written by chant 0.124.29 and newer. Set on a release gate whose release was cut from a commit with a ci/revoked/<sha> tag, judged as release cut judges it: the tag. The gate's state is then superseded, or expired when its pending fact has expired. Absent otherwise." },
         "expiresAt": { "type": "string" },
         "approvals": {
           "description": "The approvals that count toward the gate for its plan, oldest first.",
@@ -904,6 +1050,59 @@
               }
             }
           ]
+        },
+        "mixed": { "$ref": "#/$defs/mixed" }
+      }
+    },
+    "mixed": {
+      "type": "object",
+      "description": "Added in contract 1 by #4035, written by chant 0.124.29 and newer. Set when the environment runs a mix: a components promote, rollback or redeploy left a component failed or gated (its <env>/outcomes.jsonl on chant/lifecycle says so) and the release ledger has recorded nothing for it since, or the latest records of its components name more than one release, a record of no release counting as one, with at least one naming a release. Derived when read. Absent otherwise.",
+      "required": ["components", "redeploy", "rollback"],
+      "properties": {
+        "components": {
+          "description": "Every component the ledger records in the environment or a run left unsettled, sorted by name.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["component", "digest", "releaseDigest", "releaseLabel", "state", "attempt"],
+            "properties": {
+              "component": { "type": "string" },
+              "digest": { "type": ["string", "null"], "description": "The digest the release ledger records the component running, or null when it has no record in the environment." },
+              "releaseDigest": { "type": ["string", "null"], "description": "The release that record names, or null." },
+              "releaseLabel": { "type": ["string", "null"], "description": "That release's label, or null." },
+              "state": {
+                "enum": ["settled", "failed", "gated"],
+                "description": "settled: the record is what the component runs. failed or gated: the newest run that named it failed on it or stopped at its gate after the steps before the gate ran, and nothing has been recorded for it since, so what it runs is not known."
+              },
+              "attempt": {
+                "description": "For an unsettled component, the run that left it so and what it was deploying. Null when settled.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["verb", "runId", "timestamp", "digest", "releaseDigest", "releaseLabel"],
+                    "properties": {
+                      "verb": { "enum": ["promote", "rollback", "redeploy"] },
+                      "runId": { "type": "string" },
+                      "timestamp": { "type": "string" },
+                      "digest": { "type": "string" },
+                      "releaseDigest": { "type": ["string", "null"] },
+                      "releaseLabel": { "type": ["string", "null"] }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "redeploy": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "chant components redeploy <env> --component <component> for each unsettled component the ledger records, run in the member's directory: it puts the component's recorded release back. Empty when no component is unsettled."
+        },
+        "rollback": {
+          "type": ["string", "null"],
+          "description": "chant components rollback <env> --release <label|digest>, run in the member's directory: it restores every component of the newest release the environment ran, other than the one it was moving to, that is still kept and not revoked. Null when there is none."
         }
       }
     },
@@ -912,19 +1111,86 @@
       "required": ["component", "digest", "gitSha", "inputDigest", "runId", "timestamp", "actor", "flags", "plan"],
       "properties": {
         "component": { "type": "string" },
-        "digest": { "type": "string", "description": "The artifact digest the release deployed." },
+        "digest": { "type": "string", "description": "What the deploy record names, as its producer writes it: an artifact digest, a release-plan digest for a runner that records plans (_plans/<digest>.json, ws-055), or a product's own digest such as a schema digest (ws-104 question 3)." },
         "gitSha": { "type": "string", "description": "The commit the artifact was built from." },
         "inputDigest": { "type": ["string", "null"], "description": "The input-side digest when digest is a rendered one. Compare joins on it when present." },
         "runId": { "type": "string" },
         "timestamp": { "type": "string" },
         "actor": { "type": "string" },
+        "approver": { "type": ["string", "null"], "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer; the ledger has carried it since #1035. Who approved the change at its gate, or null for an ungated release." },
+        "admission": {
+          "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The gate resolution that admitted the release, or null for an ungated release and for one recorded by an older chant. With approver it names the line in the gate ledger.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["op", "gate", "resolvedAt"],
+              "properties": {
+                "op": { "type": "string", "description": "The op, or for a component gate the component, whose gate ledger (_gates/<op>.jsonl) holds the resolution." },
+                "gate": { "type": "string", "description": "The gate's name." },
+                "resolvedAt": { "type": "string", "description": "When the resolution was recorded. The newest one, when several approvals counted." }
+              }
+            }
+          ]
+        },
+        "releaseDigest": { "type": ["string", "null"], "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4043, written by chant 0.124.29 and newer. The release this deploy was made from: the releaseDigest of _releases/<releaseDigest>.json. A promote with --release writes it, a run --components with --release writes it, and a rollback or redeploy copies it from the record it restores. Null for a deploy that named no release. With the item's environment it names the release target." },
+        "releaseLabel": { "type": ["string", "null"], "description": "Added in contract 1 by #4043, written by chant 0.124.29 and newer. The label that release was cut with, from _releases/cuts.jsonl. Null when releaseDigest is null, when the release has no label, and when the cuts can't be read." },
         "flags": { "type": "array", "items": { "enum": ["legacy-digest"] } },
         "plan": {
           "type": ["object", "null"],
           "description": "The release plan digest names, read from _plans/<digest>.json on chant/lifecycle (ws-055, #2733): the work items and evidence this release shipped. Null when this checkout has no plan stored under that digest — most releases carry no plan, and a plan not yet fetched also reads null."
+        },
+        "revoked": {
+          "description": "Added in contract 1 by #4033 (ws-105), written by chant 0.124.29 and newer. Set when the deploy record names a release in releaseDigest and that release was cut from a commit with a ci/revoked/<sha> tag: the environment runs a revoked release. Read from local tags at read time and judged as release cut judges them, so with ci.green.signedSince an unsigned revoked tag is ignored. Absent when the release is not revoked, when the record names no release, and when the ci tags can't be judged.",
+          "allOf": [
+            { "$ref": "#/$defs/revocation" },
+            {
+              "type": "object",
+              "required": ["releaseDigest", "label", "rollback"],
+              "properties": {
+                "releaseDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The revoked release the environment runs." },
+                "label": { "type": ["string", "null"], "description": "The release's label, or null when its cuts gave it none." },
+                "rollback": { "type": "string", "description": "The line that rolls the environment back, run in the member's directory. Since #4035 (chant 0.124.29): chant components rollback <env> --release <label|digest>, naming the newest release the environment ran before this one that is still kept and not revoked. When there is none, and from chant 0.124.28: chant components rollback <env> --component <component>." }
+              }
+            }
+          ]
         }
       }
     },
+    "revocation": {
+      "type": "object",
+      "description": "The ci/revoked/<sha> tag on a release's commit (#4033, ws-105), as chant ci list --json shows a commit's revoked tag, with the commit.",
+      "required": ["commit", "tag", "tagged", "phase", "run", "signer"],
+      "properties": {
+        "commit": { "type": "string", "description": "The release's commit, which the tag names." },
+        "tag": { "type": "string", "description": "ci/revoked/<sha>." },
+        "tagged": { "type": ["string", "null"], "description": "When the tag was made, ISO 8601, or null for a lightweight tag." },
+        "phase": { "type": ["string", "null"], "description": "The phase the annotation names as failed, or null when the annotation can't be read." },
+        "run": {
+          "description": "The run the annotation names as failed, or null.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["name", "id", "conclusion", "url"],
+              "properties": {
+                "name": { "type": "string" },
+                "id": { "type": ["integer", "null"], "description": "The check run's id, or null for a chant Op run." },
+                "conclusion": { "type": ["string", "null"] },
+                "url": { "type": ["string", "null"] },
+                "opRun": {
+                  "type": "object",
+                  "required": ["id", "env", "signer"],
+                  "properties": { "id": { "type": "string" }, "env": { "type": "string" }, "signer": { "type": "string" } },
+                  "description": "Present only when the run is a chant Op run (ci.green.source runs, #4044): its id, the env it is recorded under and the runner whose statement it carries. id is then null."
+                }
+              }
+            }
+          ]
+        },
+        "signer": { "type": ["string", "null"], "description": "The runner principal whose statement the tag carries, or null when it counts unsigned." }
+      }
+    },
     "compare": {
       "type": "object",
       "required": ["differs", "components"],

package/dist/workspace/trust/ci-tag-statement.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The statement a ci tag carries (#4031): a runner's signed word that a
+ * commit went green, or went red after it was green.
+ *
+ * `ci/green/<sha>` and `ci/revoked/<sha>` are plain git tags (ws-103), so
+ * anyone who may push a tag could make one by hand and go around CI. When the
+ * declaration sets `ci.green.signedSince` to a commit, a tag on any commit
+ * that is not a strict first-parent ancestor of it counts only when its
+ * annotation holds a statement signed by a runner key, and readers ignore
+ * and report a tag without a valid one.
+ *
+ * The statement reuses what runner evidence (#2553, ws-069) and the agent-run
+ * statement (#3192, ws-090) already use: an in-toto Statement v1 in a DSSE
+ * envelope (./dsse.ts), signed with an Ed25519 key that `.chant/trust.json`
+ * at base lists under `runners`. The key's principal must also hold the
+ * `runner` role there, since a tag says CI ran. A key the signers file lists
+ * is never a runner key (./policy.ts).
+ *
+ * - `subject`: the tagged commit, by `digest.gitCommit`.
+ * - `predicate`: the signer's principal and the tag's JSON record as the
+ *   annotation holds it (`tag`, `commit`, `branch`, `at`, and the phases'
+ *   runs for a green tag or the failed phase and run for a revoked one).
+ *
+ * The envelope sits in the annotation's JSON record as `statement`, beside
+ * the fields it signs, so a reader that does not know it reads the record as
+ * before. Verifying needs the tag, the envelope and the runner keys at base,
+ * so it works offline, and every read verifies again.
+ */
+import { z } from "zod";
+import { type DsseEnvelope } from "./dsse.js";
+import type { KeyObject } from "node:crypto";
+import type { RunnerKey } from "./policy.js";
+export declare const CI_TAG_PREDICATE = "https://intentius.io/chant/ci-tag/v1";
+/** The role a tag's signer must hold in `.chant/trust.json` (#4031): the core class `runner`. */
+export declare const CI_TAG_SIGNER_ROLE = "runner";
+/** The statement a ci tag carries. Strict at the top, so a verifier never acts on a field it does not know. */
+export declare const ciTagStatementSchema: z.ZodObject<{
+    _type: z.ZodLiteral<"https://in-toto.io/Statement/v1">;
+    subject: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        digest: z.ZodObject<{
+            gitCommit: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    predicateType: z.ZodLiteral<"https://intentius.io/chant/ci-tag/v1">;
+    predicate: z.ZodObject<{
+        signer: z.ZodString;
+        record: z.ZodObject<{
+            schema: z.ZodLiteral<1>;
+            tag: z.ZodEnum<{
+                green: "green";
+                revoked: "revoked";
+            }>;
+            commit: z.ZodString;
+            branch: z.ZodString;
+            at: z.ZodString;
+        }, z.core.$loose>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CiTagStatement = z.infer<typeof ciTagStatementSchema>;
+/** A tag's JSON record, without the statement. */
+export type CiTagRecord = Record<string, unknown> & {
+    tag: "green" | "revoked";
+    commit: string;
+    branch: string;
+};
+/** Whoever signs the tags a tick makes: a runner key and the principal `.chant/trust.json` lists it for. */
+export interface CiTagSigner {
+    principal: string;
+    key: KeyObject;
+    publicKey: string;
+}
+export declare function buildCiTagStatement(record: CiTagRecord, signer: string): CiTagStatement;
+/** The envelope a tag's record carries as `statement`, signed by `signer`. */
+export declare function signCiTagRecord(record: CiTagRecord, signer: CiTagSigner): DsseEnvelope;
+/**
+ * Why a tag is ignored: it has no statement, the statement is not one, no
+ * runner key at base signed it, or it signs another tag's facts. The same
+ * words a run's attestation uses (`./run-statement.ts`).
+ */
+export type CiTagFailure = "unsigned" | "invalid" | "untrusted" | "mismatch";
+export type CiTagVerdict = {
+    status: "signed";
+    signer: string;
+    keyid: string;
+    reason: string;
+} | {
+    status: CiTagFailure;
+    reason: string;
+};
+/**
+ * Verify the statement in a tag's record. `expect` is what the tag itself
+ * says: the commit its name gives, its kind and the declared branch. The
+ * signer's key must be a runner key at base and its principal must hold the
+ * `runner` role in `roles`. Never throws.
+ */
+export declare function verifyCiTagStatement(record: Record<string, unknown> | null, expect: {
+    sha: string;
+    kind: "green" | "revoked";
+    branch: string;
+}, runners: readonly RunnerKey[], roles: Readonly<Record<string, readonly string[]>>): CiTagVerdict;
+//# sourceMappingURL=ci-tag-statement.d.ts.map

package/dist/workspace/trust/ci-tag-statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-tag-statement.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ci-tag-statement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,eAAO,MAAM,gBAAgB,yCAAyC,CAAC;AAEvE,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAK3C,+GAA+G;AAC/G,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;kBAqBtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAOvF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAGtF;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAE7E,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAI7C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACtC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClE,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GACjD,YAAY,CAgCd"}

package/dist/workspace/trust/ci-tag-statement.js

@@ -0,0 +1,123 @@
+/**
+ * The statement a ci tag carries (#4031): a runner's signed word that a
+ * commit went green, or went red after it was green.
+ *
+ * `ci/green/<sha>` and `ci/revoked/<sha>` are plain git tags (ws-103), so
+ * anyone who may push a tag could make one by hand and go around CI. When the
+ * declaration sets `ci.green.signedSince` to a commit, a tag on any commit
+ * that is not a strict first-parent ancestor of it counts only when its
+ * annotation holds a statement signed by a runner key, and readers ignore
+ * and report a tag without a valid one.
+ *
+ * The statement reuses what runner evidence (#2553, ws-069) and the agent-run
+ * statement (#3192, ws-090) already use: an in-toto Statement v1 in a DSSE
+ * envelope (./dsse.ts), signed with an Ed25519 key that `.chant/trust.json`
+ * at base lists under `runners`. The key's principal must also hold the
+ * `runner` role there, since a tag says CI ran. A key the signers file lists
+ * is never a runner key (./policy.ts).
+ *
+ * - `subject`: the tagged commit, by `digest.gitCommit`.
+ * - `predicate`: the signer's principal and the tag's JSON record as the
+ *   annotation holds it (`tag`, `commit`, `branch`, `at`, and the phases'
+ *   runs for a green tag or the failed phase and run for a revoked one).
+ *
+ * The envelope sits in the annotation's JSON record as `statement`, beside
+ * the fields it signs, so a reader that does not know it reads the record as
+ * before. Verifying needs the tag, the envelope and the runner keys at base,
+ * so it works offline, and every read verifies again.
+ */
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt.js";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope } from "./dsse.js";
+import { STATEMENT_TYPE } from "./evidence.js";
+export const CI_TAG_PREDICATE = "https://intentius.io/chant/ci-tag/v1";
+/** The role a tag's signer must hold in `.chant/trust.json` (#4031): the core class `runner`. */
+export const CI_TAG_SIGNER_ROLE = "runner";
+const fullCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const text = z.string().min(1);
+/** The statement a ci tag carries. Strict at the top, so a verifier never acts on a field it does not know. */
+export const ciTagStatementSchema = z
+    .object({
+    _type: z.literal(STATEMENT_TYPE),
+    subject: z
+        .array(z
+        .object({ name: fullCommit, digest: z.object({ gitCommit: fullCommit }).strict() })
+        .strict()
+        .refine((s) => s.name === s.digest.gitCommit, "a commit subject is named by its own id"))
+        .length(1),
+    predicateType: z.literal(CI_TAG_PREDICATE),
+    predicate: z
+        .object({
+        signer: text,
+        record: z
+            .object({ schema: z.literal(1), tag: z.enum(["green", "revoked"]), commit: fullCommit, branch: text, at: text })
+            .passthrough(),
+    })
+        .strict(),
+})
+    .strict();
+export function buildCiTagStatement(record, signer) {
+    return {
+        _type: STATEMENT_TYPE,
+        subject: [{ name: record.commit, digest: { gitCommit: record.commit } }],
+        predicateType: CI_TAG_PREDICATE,
+        predicate: { signer, record: record },
+    };
+}
+/** The envelope a tag's record carries as `statement`, signed by `signer`. */
+export function signCiTagRecord(record, signer) {
+    const statement = buildCiTagStatement(record, signer.principal);
+    return signEnvelope(IN_TOTO_PAYLOAD_TYPE, Buffer.from(canonicalJson(statement), "utf8"), signer.key, signer.publicKey);
+}
+const normalise = (name) => name.normalize("NFKC").trim().toLowerCase();
+/**
+ * Verify the statement in a tag's record. `expect` is what the tag itself
+ * says: the commit its name gives, its kind and the declared branch. The
+ * signer's key must be a runner key at base and its principal must hold the
+ * `runner` role in `roles`. Never throws.
+ */
+export function verifyCiTagStatement(record, expect, runners, roles) {
+    const tag = `ci/${expect.kind}/${expect.sha}`;
+    if (record === null)
+        return { status: "unsigned", reason: `${tag} has no JSON record in its annotation, so it carries no statement (a lightweight tag, or one made by hand)` };
+    const { statement: envelope, ...fields } = record;
+    if (envelope === undefined)
+        return { status: "unsigned", reason: `${tag} carries no statement signed by a runner key` };
+    const v = verifyEnvelope(envelope, runners);
+    if (!v.ok)
+        return { status: v.code === "envelope-untrusted" ? "untrusted" : "invalid", reason: `${tag}: ${v.reason}` };
+    if (!(roles[CI_TAG_SIGNER_ROLE] ?? []).some((p) => normalise(p) === normalise(v.principal))) {
+        return { status: "untrusted", reason: `${tag} is signed by ${v.principal}'s runner key, and ${v.principal} holds no ${CI_TAG_SIGNER_ROLE} role in .chant/trust.json at base` };
+    }
+    if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE)
+        return { status: "invalid", reason: `${tag}: payload type ${v.payloadType} is not ${IN_TOTO_PAYLOAD_TYPE}` };
+    let raw;
+    try {
+        raw = JSON.parse(v.payload.toString("utf8"));
+    }
+    catch {
+        return { status: "invalid", reason: `${tag}: the statement's payload is not JSON` };
+    }
+    const parsed = ciTagStatementSchema.safeParse(raw);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+        return { status: "invalid", reason: `${tag}: the payload is not a ${CI_TAG_PREDICATE} statement: ${detail}` };
+    }
+    const p = parsed.data.predicate;
+    if (p.signer !== v.principal)
+        return { status: "invalid", reason: `${tag}: the statement names signer ${JSON.stringify(p.signer)}, but ${v.principal}'s key signed it` };
+    const differs = [];
+    if (parsed.data.subject[0].name !== expect.sha)
+        differs.push(`it is for commit ${parsed.data.subject[0].name.slice(0, 12)}`);
+    if (p.record.commit !== expect.sha)
+        differs.push(`its record names commit ${p.record.commit.slice(0, 12)}`);
+    if (p.record.tag !== expect.kind)
+        differs.push(`it signs a ${p.record.tag} tag`);
+    if (p.record.branch !== expect.branch)
+        differs.push(`it is for branch ${p.record.branch}, and ci.green names ${expect.branch}`);
+    if (canonicalJson(p.record) !== canonicalJson(fields))
+        differs.push("the annotation's record is not the one signed");
+    if (differs.length > 0)
+        return { status: "mismatch", reason: `${tag} is signed by ${v.principal}, but the statement does not match the tag: ${differs.join("; ")}` };
+    return { status: "signed", signer: v.principal, keyid: v.keyid, reason: `signed by ${v.principal} (${CI_TAG_SIGNER_ROLE})` };
+}