@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/records.ts

@@ -38,6 +38,7 @@ import { sourceBlock, sourceBlockProblems, transcriptDrift } from "./source-bloc
 import type { WorkspaceTree } from "./tree";
 import type { DecisionWork, WorkAcceptance, WorkLink, WorkWarningCode } from "./work";
 import type { AnswerWarningCode } from "./points";
+import type { FlagState, FlagWarningCode } from "./flags";
 
 // ── Reason codes ─────────────────────────────────────────────────────────────
 
@@ -209,8 +210,8 @@ export interface VerdictAttestation {
 }
 
 export interface RecordWarning {
-  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), and `records` adds `SEAL_WARNING_CODES` (#2688, #2878). */
-  code: RecordWarningCode | WorkWarningCode | SealWarningCode | AnswerWarningCode;
+  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), a flag kind's those of `FLAG_WARNING_CODES` (#4024), and `records` adds `SEAL_WARNING_CODES` (#2688, #2878). */
+  code: RecordWarningCode | WorkWarningCode | SealWarningCode | AnswerWarningCode | FlagWarningCode;
   message: string;
 }
 
@@ -489,6 +490,31 @@ export const recordKindSchema = z
      * Optional.
      */
     answers: z.object({ points: z.string().min(1) }).strict().optional(),
+    /**
+     * A flag kind (#4024): each record is a feature flag, a workspace record
+     * a member's build reads as one build-time parameter. The block names the
+     * fields that hold the member whose parameter it sets, the parameter's
+     * name, the flag's owner and its value per environment, and the field
+     * naming the work item the flag hides, with that work kind's file
+     * (relative to this kind file). The record's id is the flag's name.
+     *
+     * With it, `chant build --env <env>` in that member resolves the
+     * parameter from the flag (`flag-params.ts`), `chant workspace status`
+     * lists the flag under the member's `featureFlags`, and `records` warns
+     * `flag-work-unknown` for a work item no record has and `flag-stale`
+     * when every decision the work item implements is confirmed, so the
+     * flag is due for removal (`check` WSP118). Optional.
+     */
+    flag: z
+      .object({
+        member: z.string().min(1),
+        param: z.string().min(1),
+        owner: z.string().min(1),
+        values: z.string().min(1),
+        work: z.object({ field: z.string().min(1), kind: z.string().min(1) }).strict(),
+      })
+      .strict()
+      .optional(),
     /**
      * The top-level field that holds a closed record's seal (#2546, ws-003,
      * ws-063): {@link recordSeal}, the whole-file JCS/SHA-256 of the record
@@ -559,6 +585,10 @@ export const recordKindSchema = z
     message: "a work kind must have states, and its work open and done states must be listed in them",
     path: ["work"],
   })
+  .refine((k) => !k.flag || k.idField !== undefined, {
+    message: "a flag kind names its id with idField: a flag's id is its name, and a build finds it by that name",
+    path: ["flag"],
+  })
   .refine((k) => !k.work?.acceptance || k.pins !== undefined, {
     message: "a work kind with acceptance criteria must have pins: a criterion is met by the evidence in its pins field",
     path: ["work", "acceptance"],
@@ -1229,6 +1259,8 @@ export interface RecordEntry {
   acceptance?: WorkAcceptance | null;
   /** For a work kind with a contract link (#3147): the contract record the item builds, with its state, or null when it names none. */
   contract?: WorkLink | null;
+  /** For a flag kind (#4024): the work item the flag hides, the decisions it implements, and whether the flag is due for removal. */
+  flag?: FlagState;
 }
 
 export interface ReadRecordsOptions {
@@ -1575,6 +1607,8 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   const work = kind.work ? await (await import("./work")).applyWork(loaded, entries, options) : undefined;
   // An answer kind's points (ws-058): an answer whose point is gone or changed is warned about.
   if (kind.answers) (await import("./points")).applyAnswers(loaded, entries, options);
+  // A flag kind's work item and whether the flag is due for removal (#4024).
+  if (kind.flag) await (await import("./flags")).applyFlags(loaded, entries, options);
 
   for (const e of entries) e.valid = e.reasons.length === 0;
   const records = options.current ? entries.filter((e) => e.supersededBy === null) : entries;

package/src/workspace/reference-kinds/flag/flag.kind.mjs

@@ -0,0 +1,32 @@
+// The feature flag record kind (#4024), data only: no imports, no code.
+//
+// chant workspace records --kind flags/flag.kind.mjs --json
+//
+// A flag is a workspace record a member's build reads as one build-time
+// parameter: chant build --env <env> in that member takes the flag's value
+// for the environment, and records it with source flag:<id>. Turning a flag
+// on is a commit that changes this record, so it is reviewed, and the release
+// cut from that commit carries the new value through the environment's gate.
+//
+// The canonical copy ships in @intentius/chant at
+// src/workspace/reference-kinds/flag. A workspace copies this file and
+// flag.schema.json into a directory of its own, such as flags/, names the
+// kind file in chant.workspace.json's records, and points work.kind at its
+// own work kind file.
+export const recordKind = {
+  name: "flag",
+  location: { dir: ".", match: "^[a-z][a-z0-9-]{0,62}\\.flag\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:flag:1", path: "flag.schema.json" },
+  idField: "id",
+  // The fields chant reads as the flag: the member and parameter it sets,
+  // its owner, its value per environment, and the work item it hides, a
+  // record of the work kind named here (relative to this file).
+  flag: {
+    member: "member",
+    param: "param",
+    owner: "owner",
+    values: "values",
+    work: { field: "work", kind: "../work/work.kind.mjs" },
+  },
+};

package/src/workspace/reference-kinds/flag/flag.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:intentius:chant:flag:1",
+  "title": "Feature flag front matter",
+  "description": "The front matter of one feature flag record (#4024): a workspace record one member's build reads as a build-time parameter. The file is named <id>.flag.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {}
+  },
+  "required": ["schema", "id", "owner", "work", "member", "param", "values"],
+  "properties": {
+    "schema": {
+      "description": "Format version of this file. Bumped only by a change to this schema.",
+      "const": 1
+    },
+    "id": {
+      "description": "The flag's name, which the build records as the source flag:<id> of the parameter it sets. Lowercase, with dashes.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,62}$"
+    },
+    "title": {
+      "description": "What the flag hides, in a few words. Optional.",
+      "type": "string"
+    },
+    "owner": {
+      "description": "Who owns the flag, and removes it once its work is settled.",
+      "type": "string",
+      "minLength": 1
+    },
+    "work": {
+      "description": "The id of the work item the flag hides, a record of the work kind the flag kind names. A work item's implements names a decision, never a flag, so the link is kept here.",
+      "type": "string",
+      "minLength": 1
+    },
+    "member": {
+      "description": "The workspace member whose build parameter the flag sets, by its name in chant.workspace.json.",
+      "type": "string",
+      "minLength": 1
+    },
+    "param": {
+      "description": "The build parameter the flag sets: a key of buildParams in the member's chant.config.ts. Its value per environment must have the parameter's type and, when it declares one, be in its enum.",
+      "type": "string",
+      "minLength": 1
+    },
+    "values": {
+      "description": "The flag's value per environment, keyed by the environment's name. An environment left out builds with the parameter's declared default.",
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+      "additionalProperties": { "type": ["string", "number", "boolean"] }
+    }
+  }
+}

package/src/workspace/releases.schema.json

@@ -0,0 +1,513 @@
+{
+  "$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"
+                }
+              }
+            }
+          }
+        },
+        "revoked": {
+          "description": "Added within contract version 1 by #4033, written by chant 0.124.29 and newer. The ci/revoked/<sha> tag on the release's commit, or null when the commit is not revoked. A revoked release is never promoted (chant components promote --release refuses it) and its pending release gates refuse approval. Null too when the ci tags can't be judged, as when ci.green.signedSince names no commit here, which chant workspace check reports.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/revocation"
+            }
+          ]
+        }
+      }
+    },
+    "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."
+        },
+        "runId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added by #4027, written by chant 0.124.29 and newer. The run the cut ran in: the CI run's id in CI (GITHUB_RUN_ID, CI_PIPELINE_ID), or outside CI an id minted on the machine that cut, local-<epoch ms>. Null on a cut written before 0.124.29."
+        },
+        "runOrigin": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge"
+              ],
+              "properties": {
+                "forge": {
+                  "enum": [
+                    "github",
+                    "gitlab",
+                    "op",
+                    "local"
+                  ]
+                },
+                "repo": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The run the cut ran in: the forge (github for GitHub and Forgejo, gitlab, or local for an id minted outside CI), the repo or project, and a link to the run. From chant 0.124.29 a cut outside CI writes { forge: local } (#4027); a cut written before reads 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"
+            }
+          }
+        }
+      }
+    },
+    "revocation": {
+      "type": "object",
+      "description": "A revoked tag on a release's commit (#4033, ws-105), as chant ci list --json shows a commit's revoked tag, with the commit. Read from local tags at read time and judged as release cut judges them: with ci.green.signedSince, a revoked tag without a valid runner statement is ignored and revokes nothing.",
+      "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 above is then null."
+                }
+              }
+            }
+          ]
+        },
+        "signer": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The runner principal whose statement the tag carries, or null when it counts unsigned."
+        }
+      }
+    }
+  }
+}