@intentius/chant 0.124.28 → 0.124.29

package/src/workspace/overlap.ts

@@ -0,0 +1,340 @@
+/**
+ * Overlap between in-flight work items (#4025, policy from #4016).
+ *
+ * A work lease locks one item, and nothing compares two items with each
+ * other. This report does, after the fact: it says which in-flight work items
+ * changed the same files, and which entries of a planned change set more than
+ * one of them reaches. It never blocks anything. Two people or agents read it
+ * and sort the overlap out between them.
+ *
+ * ## In flight
+ *
+ * A work item is a current record of a declared work kind. It is in flight
+ * unless it implements at least one decision and every decision it implements
+ * is confirmed, as #4024 defines confirmed ({@link decisionConfirmed}: in one
+ * of the decision kind's closed states and superseded by nothing). The item's
+ * own state does not matter: work marked done whose decision is not settled
+ * can still collide.
+ *
+ * ## Linked commits
+ *
+ * The commits of a work item are the commits linked to it as #4029 defines
+ * linked ({@link judgeCommits}): a `Chant-Record: <work kind>:<id>` trailer,
+ * or a `Chant-Lease` trailer that resolves to the item. A window match does
+ * not link. The walk covers every local branch, every remote-tracking branch
+ * and HEAD, so work pushed to a branch and fetched shows before it is merged.
+ * The ledger branches under `chant/` hold no work and are left out. Merge
+ * commits carry no work of their own and are skipped. Nothing is fetched.
+ *
+ * ## Files
+ *
+ * An item's files are the paths its linked commits add, change or delete,
+ * from the repository root, with renames read as a delete and an add. Two
+ * items overlap by file when both touch one path.
+ *
+ * ## Change-set entries
+ *
+ * A change set is planned from many commits, and a release bundles many work
+ * items, so an entry belongs to no single item on its face. An entry is
+ * attributed to a work item when:
+ *
+ * 1. the entry has a `source`: the file that declares its graph node, from
+ *    the repository root, recorded when the change set was stored
+ *    (`../change-set-graph.ts`);
+ * 2. a commit linked to the item changed that file; and
+ * 3. that commit is in the history the change set was planned from: an
+ *    ancestor of (or equal to) the commit its graph was read at, else the
+ *    commit the gate was reached at. When neither is known, or the commit is
+ *    not in this repository, the third test is skipped.
+ *
+ * An entry can be attributed to several items, and two items overlap by
+ * address when one entry is attributed to both. An entry with no `source`
+ * (stored by an older chant, mapped onto no node, or a node with no source
+ * location) is attributed to none and counted in `unattributed`.
+ *
+ * The change sets read are the ones `workspace status` lists on a gate that
+ * is pending or approved: the plans still waiting to apply.
+ */
+
+import { execFileSync } from "node:child_process";
+import { dirname } from "node:path";
+import type { ChangeSetDocument } from "../change-set";
+import { judgeCommits, hasLeaseLedger, type WorkIndex } from "./commit-links";
+import { declaredRecordKinds, type Declaration } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import { decisionConfirmed } from "./flags";
+import { loadRecordKind } from "./records";
+import { readRecordsFor } from "./records-cli";
+import { LEASE_TRAILER, RECORD_TRAILER } from "./trailers";
+
+/** One in-flight work item with at least one linked commit. */
+export interface OverlapItem {
+  /** `<work kind>:<id>`, as a `Chant-Record` trailer names it. */
+  item: string;
+  /** The work record file, from the repository root. */
+  path: string;
+  state: string | null;
+  /** The commits linked to the item, newest first. */
+  commits: string[];
+}
+
+/** One change-set entry two items both reach. */
+export interface OverlapAddress {
+  /** The change set's digest, as `chant change-set show` takes it. */
+  changeSet: string;
+  /** The workspace member whose ledger stores the change set, or null for the flat ledger. */
+  ledgerMember: string | null;
+  /** The entry's change-set member and planner address. */
+  member: string;
+  address: string;
+  /** The entry's graph node, or null. */
+  node: string | null;
+  /** The source file the attribution went through, from the repository root. */
+  source: string;
+}
+
+/** Two in-flight work items that changed the same thing. */
+export interface OverlapPair {
+  /** The two items, `<work kind>:<id>`, in sorted order. */
+  items: [string, string];
+  /** The files both items' linked commits touch, sorted. */
+  files: string[];
+  /** The change-set entries attributed to both items, by change set then address. */
+  addresses: OverlapAddress[];
+}
+
+/** What `workspace status` reports as `overlap`. */
+export interface OverlapReport {
+  /** The in-flight work items with a linked commit, by item. */
+  items: OverlapItem[];
+  /** Each pair of items that share a file or an entry, by the first item then the second. */
+  pairs: OverlapPair[];
+  /** The digests of the change sets read, sorted. */
+  changeSets: string[];
+  /** Entries of those change sets with no `source`, so attributed to no item. */
+  unattributed: number;
+}
+
+/** A change set to attribute: one a pending or approved gate binds. */
+export interface OverlapChangeSetRef {
+  digest: string;
+  /** A directory whose ledger stores it: the member's directory. */
+  cwd: string;
+  ledgerMember: string | null;
+  /** The commit the gate was reached at, when the pending fact records one. */
+  gitSha: string | null;
+}
+
+/** Reads a stored change set; the lifecycle store unless a test swaps it. */
+export type StoredChangeSetReader = (digest: string, cwd: string) => Promise<ChangeSetDocument | null>;
+
+const defaultReadChangeSet: StoredChangeSetReader = async (digest, cwd) => {
+  const { readStoredChangeSet } = await import("../lifecycle/change-set-store");
+  const read = await readStoredChangeSet(digest, { cwd });
+  return read.status === "found" ? read.document : null;
+};
+
+function git(top: string, args: string[], input?: string): string {
+  return execFileSync("git", ["-c", "core.quotepath=off", ...args], {
+    cwd: top,
+    encoding: "utf-8",
+    stdio: [input === undefined ? "ignore" : "pipe", "pipe", "ignore"],
+    maxBuffer: 512 * 1024 * 1024,
+    ...(input !== undefined ? { input } : {}),
+  });
+}
+
+/** The work items of every declared work kind, with the index commits are judged against and the ones in flight. */
+async function readWorkItems(declaration: Declaration, root: string, top: string): Promise<{ index: WorkIndex; inFlight: Map<string, { path: string; state: string | null }> } | null> {
+  const kinds = new Map<string, Set<string>>();
+  const inFlight = new Map<string, { path: string; state: string | null }>();
+  for (const d of declaredRecordKinds(declaration)) {
+    const file = declaredKindFile(d, root);
+    const loaded = await loadRecordKind(file, root);
+    if (!loaded.kind.work) continue;
+    const decisionKind = await loadRecordKind(loaded.kind.work.decisions, dirname(loaded.file));
+    const closed = new Set(decisionKind.kind.closedStates ?? []);
+    const read = await readRecordsFor({ kind: file, cwd: root });
+    const decisions = new Map((read.result.decisions ?? []).map((x) => [x.id, x]));
+    const ids = kinds.get(loaded.kind.name) ?? new Set<string>();
+    for (const r of read.result.records) {
+      if (r.id === null) continue;
+      ids.add(r.id);
+      if (r.supersededBy !== null) continue;
+      const implemented = r.implements ?? [];
+      const settled = implemented.length > 0 && implemented.every((x) => decisionConfirmed(decisions.get(x.id), closed));
+      const key = `${loaded.kind.name}:${r.id}`;
+      if (!settled && !inFlight.has(key)) inFlight.set(key, { path: r.path, state: r.state });
+    }
+    kinds.set(loaded.kind.name, ids);
+  }
+  if (kinds.size === 0) return null;
+  return { index: { kinds, ledger: hasLeaseLedger(top) }, inFlight };
+}
+
+/**
+ * The non-merge commits on every local and remote-tracking branch and HEAD
+ * that carry a `Chant-Record` or `Chant-Lease` trailer, newest first. The
+ * ledger branches under `chant/` are left out.
+ */
+export function trailerCommits(top: string): string[] {
+  let text: string;
+  try {
+    text = git(top, [
+      "log",
+      "--no-merges",
+      `--format=%H%x1f%(trailers:key=${RECORD_TRAILER},key=${LEASE_TRAILER},valueonly,separator=%x1e)%x1d`,
+      "--exclude=chant/*",
+      "--branches",
+      "--exclude=*/chant/*",
+      "--remotes",
+      "HEAD",
+      "--",
+    ]);
+  } catch {
+    // An unborn HEAD has no history to read.
+    return [];
+  }
+  const out: string[] = [];
+  for (const chunk of text.split("\x1d")) {
+    const [sha, trailers] = chunk.trim().split("\x1f");
+    if (sha && trailers && trailers.trim() !== "") out.push(sha);
+  }
+  return out;
+}
+
+/** The paths each commit adds, changes or deletes, from the repository root, renames read as a delete and an add. */
+export function commitFiles(top: string, shas: string[]): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  if (shas.length === 0) return out;
+  const text = git(top, ["log", "--no-walk=unsorted", "--stdin", "--no-renames", "--name-only", "--format=%x1e%H"], `${shas.join("\n")}\n`);
+  for (const block of text.split("\x1e")) {
+    const lines = block.split("\n").map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0) continue;
+    out.set(lines[0], lines.slice(1));
+  }
+  return out;
+}
+
+/** Every commit reachable from `rev`, or null when `rev` is not in the repository. */
+function reachable(top: string, rev: string): Set<string> | null {
+  try {
+    return new Set(git(top, ["rev-list", rev, "--"]).split("\n").filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
+const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The work items a change-set entry is attributed to, sorted: each item with
+ * a linked commit that changed the entry's `source` and is in `within`, the
+ * history the change set was planned from (null when that is unknown, so
+ * every linked commit counts). An entry with no source has none.
+ *
+ * `commitsOf` maps each in-flight item to its linked commits, and `files`
+ * each commit to the paths it touches.
+ */
+export function attributeEntry(
+  source: string | undefined,
+  commitsOf: ReadonlyMap<string, readonly string[]>,
+  files: ReadonlyMap<string, readonly string[]>,
+  within: ReadonlySet<string> | null,
+): string[] {
+  if (source === undefined) return [];
+  const out: string[] = [];
+  for (const [item, commits] of commitsOf) {
+    if (commits.some((sha) => (files.get(sha) ?? []).includes(source) && (within === null || within.has(sha)))) out.push(item);
+  }
+  return out.sort(byString);
+}
+
+/**
+ * The overlap report for the workspace declared at `root` in the repository
+ * at `top`. Null when the declaration names no work kind. Throws when a work
+ * kind or its records can't be read, or git fails; `workspace status` writes
+ * null then.
+ */
+export async function readOverlap(input: {
+  declaration: Declaration;
+  root: string;
+  top: string;
+  changeSets: OverlapChangeSetRef[];
+  readChangeSet?: StoredChangeSetReader;
+}): Promise<OverlapReport | null> {
+  const { top } = input;
+  const work = await readWorkItems(input.declaration, input.root, top);
+  if (work === null) return null;
+
+  // The commits of each in-flight item, newest first.
+  const commitsOf = new Map<string, string[]>();
+  if (work.inFlight.size > 0) {
+    const candidates = trailerCommits(top);
+    const links = judgeCommits(top, candidates, work.index);
+    for (const sha of candidates) {
+      for (const id of links.get(sha)?.ids ?? []) {
+        if (!work.inFlight.has(id)) continue;
+        const list = commitsOf.get(id) ?? [];
+        if (!list.includes(sha)) list.push(sha);
+        commitsOf.set(id, list);
+      }
+    }
+  }
+  const items = [...commitsOf.keys()].sort(byString);
+  const files = commitFiles(top, [...new Set([...commitsOf.values()].flat())]);
+  const filesOf = new Map(items.map((id) => [id, new Set(commitsOf.get(id)!.flatMap((sha) => files.get(sha) ?? []))]));
+
+  // Each change-set entry with a source, attributed to the items whose linked commits changed it within the change set's history.
+  const read = input.readChangeSet ?? defaultReadChangeSet;
+  const seen = new Set<string>();
+  const changeSets: string[] = [];
+  let unattributed = 0;
+  const addressesOf = new Map<string, OverlapAddress[]>();
+  const history = new Map<string, Set<string> | null>();
+  for (const ref of input.changeSets) {
+    const key = `${ref.ledgerMember ?? ""}\0${ref.digest}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const doc = await read(ref.digest, ref.cwd);
+    if (doc === null) continue;
+    if (!changeSets.includes(doc.digest)) changeSets.push(doc.digest);
+    const at = doc.graph?.at ?? ref.gitSha;
+    for (const e of doc.entries) {
+      if (e.source === undefined) {
+        unattributed++;
+        continue;
+      }
+      // Only an entry two items could share needs the change set's history.
+      if (attributeEntry(e.source, commitsOf, files, null).length < 2) continue;
+      if (at && !history.has(at)) history.set(at, reachable(top, at));
+      const owners = attributeEntry(e.source, commitsOf, files, at ? history.get(at)! : null);
+      if (owners.length < 2) continue;
+      const address: OverlapAddress = { changeSet: doc.digest, ledgerMember: ref.ledgerMember, member: e.member, address: e.address, node: e.node ?? null, source: e.source };
+      for (const id of owners) addressesOf.set(id, [...(addressesOf.get(id) ?? []), address]);
+    }
+  }
+  changeSets.sort(byString);
+
+  const pairs: OverlapPair[] = [];
+  for (let i = 0; i < items.length; i++) {
+    for (let j = i + 1; j < items.length; j++) {
+      const a = items[i];
+      const b = items[j];
+      const fb = filesOf.get(b)!;
+      const shared = [...filesOf.get(a)!].filter((f) => fb.has(f)).sort(byString);
+      const ab = addressesOf.get(b) ?? [];
+      const addresses = (addressesOf.get(a) ?? [])
+        .filter((x) => ab.includes(x))
+        .sort((x, y) => byString(x.changeSet, y.changeSet) || byString(x.member, y.member) || byString(x.address, y.address));
+      if (shared.length > 0 || addresses.length > 0) pairs.push({ items: [a, b], files: shared, addresses });
+    }
+  }
+
+  return {
+    items: items.map((id) => ({ item: id, path: work.inFlight.get(id)!.path, state: work.inFlight.get(id)!.state, commits: commitsOf.get(id)! })),
+    pairs,
+    changeSets,
+    unattributed,
+  };
+}

package/src/workspace/read-contract.e2e.test.ts

@@ -46,13 +46,14 @@ import { workspacePoints } from "./points-cli";
 import pointsSchema from "./points.schema.json";
 import releasesSchema from "./releases.schema.json";
 import changeSetShowSchema from "./change-set-show.schema.json";
+import deliveryMetricsSchema from "./delivery-metrics.schema.json";
 import { workspaceStatus } from "./status";
 import statusSchema from "./status.schema.json";
 
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema, "ci-last-green": ciLastGreenSchema, "ci-list": ciListSchema, releases: releasesSchema, "change-set-show": changeSetShowSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema, "ci-last-green": ciLastGreenSchema, "ci-list": ciListSchema, releases: releasesSchema, "change-set-show": changeSetShowSchema, "delivery-metrics": deliveryMetricsSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {

package/src/workspace/reason-codes.test.ts

@@ -34,6 +34,7 @@ import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
 import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
+import { FLAG_WARNING_CODES } from "./flags";
 import { POINTS_ERROR_CODES, POINTS_SOURCE_REASON_CODES } from "./points-cli";
 import { POINTS_WRITE_ERROR_CODES } from "./decide";
 import { PATCH_ERROR_CODES } from "./patch";
@@ -50,6 +51,7 @@ import { CI_GREEN_ERROR_CODES } from "./ci-green";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
+import { METRICS_ERROR_CODES, METRICS_REASON_CODES } from "./delivery-metrics";
 
 const HERE = import.meta.dirname;
 
@@ -101,6 +103,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RUN_STATEMENT_FAILURE_CODES,
   WORK_EVIDENCE_ERROR_CODES,
   RECORD_FINDING_CODES,
+  FLAG_WARNING_CODES,
   ANSWER_WARNING_CODES,
   POINTS_ERROR_CODES,
   POINTS_SOURCE_REASON_CODES,
@@ -121,6 +124,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   ROTATION_REFUSAL_CODES,
   SIGNERS_ERROR_CODES,
   EVIDENCE_ERROR_CODES,
+  METRICS_ERROR_CODES,
+  METRICS_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

package/src/workspace/reason-codes.ts

@@ -95,6 +95,9 @@ export const REASONS = {
   "work-contract-unknown": "A work record names a contract that no record of its kind's contract kind has.",
   "work-contract-undecided": "A work record names a contract whose state is not approved, such as a draft.",
   "work-tier-unknown": "A work record names a builder tier that its kind's work.tier.tiers does not list.",
+  // A feature flag that is valid but warned about (records, check, #4024).
+  "flag-work-unknown": "A flag record names a work item that no record of its kind's work kind has.",
+  "flag-stale": "Every decision a flag's work item implements is confirmed, so the flag is due for removal. check reports it (WSP118).",
   // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
   "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
   "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",

package/src/workspace/record-assets.test.ts

@@ -19,6 +19,7 @@ import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
 import { parseFrontMatter, RECORD_WARNING_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import { ANSWER_WARNING_CODES } from "./points";
+import { FLAG_WARNING_CODES } from "./flags";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import recordsSchema from "./records.schema.json";
@@ -172,7 +173,7 @@ describe("chant workspace records checks each pin", () => {
   test("the schema lists exactly the warning codes", () => {
     // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
     // an answer kind's the answer warnings (ws-058), and records adds record-unattested for an author seal under a signers file at base (#2688).
-    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES]);
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES, ...FLAG_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

package/src/workspace/records-contract.e2e.test.ts

@@ -14,6 +14,7 @@ import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type
 import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, recordTextDigest, REVIEW_REASON_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import { ANSWER_WARNING_CODES } from "./points";
+import { FLAG_WARNING_CODES } from "./flags";
 import schema from "./records.schema.json";
 import { PROVENANCE_LEVELS } from "./trust/attestor";
 
@@ -152,7 +153,7 @@ describe("records output schema", () => {
   test("lists exactly the warning codes the code can return", () => {
     // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
     // an answer kind's the answer warnings (ws-058), and records adds record-unattested for an author seal under a signers file at base (#2688).
-    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES]);
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES, ...FLAG_WARNING_CODES]);
   });
 
   test("every failure validates with its code", async () => {

package/src/workspace/records.schema.json

@@ -254,7 +254,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list, or (added by #4024) a flag record's work item that no record has, or a flag due for removal. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         },
@@ -322,6 +322,23 @@
           "description": "Added in contract 1 by #3147, on every parsed record of a work kind whose work block names a contract kind. The contract record the item builds, by the id in the work block's contract field, with that record's state now; state is null when no record of the contract kind has the id. Null when the item names no contract.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }]
         },
+        "flag": {
+          "description": "Added in contract 1 by #4024, on every parsed record of a flag kind (a kind with a flag block). work is the work item the flag hides, with that item's state (null when no record of the flag kind's work kind has it), or null when the record names none. implements lists each decision the item implements, with its state and confirmed: true when it is in one of its kind's closed states and nothing supersedes it. stale is true when the item implements at least one decision and every one is confirmed: the flag is due for removal, warned flag-stale, and chant workspace check reports it as WSP118.",
+          "type": "object",
+          "required": ["work", "implements", "stale"],
+          "properties": {
+            "work": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }] },
+            "implements": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["id", "state", "confirmed"],
+                "properties": { "id": { "type": "string" }, "state": { "type": ["string", "null"] }, "confirmed": { "type": "boolean" } }
+              }
+            },
+            "stale": { "type": "boolean" }
+          }
+        },
         "answers": {
           "description": "Added in contract 1 by #3147, on every record with an id of a work kind whose work block names an answer kind. The decision-point answers about the item: each answer record whose constrains names the item's id, in path order, joined by id and never copied onto the item. Read at the same revision; in the working tree, with the answers a steward keeps on the lifecycle ledger laid over it. Absent when the answer kind can't be read.",
           "type": "array",
@@ -414,7 +431,9 @@
             "answer-point-unknown",
             "answer-point-changed",
             "record-unattested",
-            "record-ratified-below-quorum"
+            "record-ratified-below-quorum",
+            "flag-work-unknown",
+            "flag-stale"
           ]
         },
         "message": { "type": "string" }

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"] }
+    }
+  }
+}