@intentius/chant 0.124.30 → 0.124.32

package/dist/workspace/ci-list.schema.json

@@ -240,8 +240,11 @@
                                     "description": "The env the run is recorded under."
                                   },
                                   "signer": {
-                                    "type": "string",
-                                    "description": "The runner principal whose statement the run carries."
+                                    "type": [
+                                      "string",
+                                      "null"
+                                    ],
+                                    "description": "The runner principal whose statement the run carries. null for an unsigned run, which counts unless ci.green.signedSince asks for a statement (#4156, chant 0.124.32 and newer)."
                                   }
                                 },
                                 "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the run is a chant Op run (ci.green.source runs): name is then the Op's name and id is null. Absent for a check run."
@@ -334,8 +337,11 @@
                                 "description": "The env the run is recorded under."
                               },
                               "signer": {
-                                "type": "string",
-                                "description": "The runner principal whose statement the run carries."
+                                "type": [
+                                  "string",
+                                  "null"
+                                ],
+                                "description": "The runner principal whose statement the run carries. null for an unsigned run, which counts unless ci.green.signedSince asks for a statement (#4156, chant 0.124.32 and newer)."
                               }
                             },
                             "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the run is a chant Op run (ci.green.source runs): name is then the Op's name and id is null. Absent for a check run."
@@ -432,7 +438,7 @@
               },
               "ignoredRuns": {
                 "type": "array",
-                "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the source is chant runs (ci.green.source or --source runs): the Op runs on the commit that do not count for want of a valid statement signed by a runner key whose principal holds the runner role. They neither green nor revoke the commit.",
+                "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the source is chant runs (ci.green.source or --source runs): the Op runs on the commit that do not count: a statement that does not verify (invalid, untrusted or mismatch), or, under ci.green.signedSince, no statement on a commit that needs one (#4156). They neither green nor revoke the commit.",
                 "items": {
                   "type": "object",
                   "required": [
@@ -460,7 +466,7 @@
                         "untrusted",
                         "mismatch"
                       ],
-                      "description": "unsigned: the record carries no statement. invalid: the statement is not an op-run statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another run, commit or record than the ledger holds."
+                      "description": "unsigned: the record carries no statement, on a commit ci.green.signedSince asks one for (#4156: without signedSince an unsigned run counts). invalid: the statement is not an op-run statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another run, commit or record than the ledger holds."
                     },
                     "reason": {
                       "type": "string"

package/dist/workspace/ci-report-url.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The report URL a command uses (#4160): `--report-url` when it is given,
+ * else the workspace declaration's `ci.reportUrl`, else none.
+ *
+ * `chant build --pr-loop`, `chant ci run`, `chant ci serve` and `chant ci
+ * runs` call this. The declaration is read from the working tree of the
+ * workspace that holds `cwd`. A directory with no declaration between it and
+ * the git root reads nothing and loads no declaration module, so a project
+ * outside a workspace behaves as before. A declaration that can't be read
+ * is an error naming its place and its reason code, such as
+ * `declaration-invalid`, since the command would otherwise run without the
+ * URL the workspace may declare.
+ */
+/** The declared `ci.reportUrl` of the workspace holding `cwd`, or undefined. */
+export declare function declaredReportUrl(cwd: string): Promise<string | undefined>;
+/** `flag` when given, else the declared `ci.reportUrl` (#4160). */
+export declare function reportUrlOf(flag: string | undefined, cwd: string): Promise<string | undefined>;
+//# sourceMappingURL=ci-report-url.d.ts.map

package/dist/workspace/ci-report-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-report-url.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-report-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,gFAAgF;AAChF,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAUhF;AAED,mEAAmE;AACnE,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEpG"}

package/dist/workspace/ci-report-url.js

@@ -0,0 +1,33 @@
+/**
+ * The report URL a command uses (#4160): `--report-url` when it is given,
+ * else the workspace declaration's `ci.reportUrl`, else none.
+ *
+ * `chant build --pr-loop`, `chant ci run`, `chant ci serve` and `chant ci
+ * runs` call this. The declaration is read from the working tree of the
+ * workspace that holds `cwd`. A directory with no declaration between it and
+ * the git root reads nothing and loads no declaration module, so a project
+ * outside a workspace behaves as before. A declaration that can't be read
+ * is an error naming its place and its reason code, such as
+ * `declaration-invalid`, since the command would otherwise run without the
+ * URL the workspace may declare.
+ */
+import { findWorkspaceRoot } from "../project-root.js";
+/** The declared `ci.reportUrl` of the workspace holding `cwd`, or undefined. */
+export async function declaredReportUrl(cwd) {
+    const found = findWorkspaceRoot(cwd);
+    if (!found)
+        return undefined;
+    const [{ readDeclaration, WorkspaceReadError }, { workingTree }] = await Promise.all([import("./declaration.js"), import("./tree.js")]);
+    try {
+        return readDeclaration(workingTree(found.dir)).ci?.reportUrl ?? undefined;
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        throw Object.assign(new Error(`${err.describe()} [${err.code}]`), { code: err.code });
+    }
+}
+/** `flag` when given, else the declared `ci.reportUrl` (#4160). */
+export async function reportUrlOf(flag, cwd) {
+    return flag ?? (await declaredReportUrl(cwd));
+}

package/dist/workspace/ci-run-index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The run index (#4098, epic #4101): where the chant runner says which jobs it
+ * ran, at the `--report-url` root, for behold and the demo kiosk to find runs
+ * without a forge or a workflow file.
+ *
+ * ```
+ * <url>/runs/index.json
+ * ```
+ *
+ * One document, `ci-run-index/v1` (`ci-run-index.schema.json`). Each settled
+ * `chant ci run` job with `--report-url` set adds an entry to its front, so
+ * the newest run is first, and the list is cut to the newest `limit` entries,
+ * 200 by default. An entry's `key` is the folder the job's report went to
+ * (`reportKey`, `<pr>/<commit>`), so a reader goes from the index to
+ * `<url>/<key>/pr-<job>.json`.
+ *
+ * The update reads the index, changes it and writes it back through the same
+ * `file://` and `s3://` paths the report upload uses (pr-report-url.ts). A
+ * `file://` write goes through a temporary name and a rename. Two runners
+ * updating one index at once can lose an entry, and that is out of scope:
+ * `chant ci serve` is one host. Within one process the updates for one URL
+ * take turns, so `ci serve --max-jobs 2` does not race itself.
+ *
+ * An index that can't be parsed is replaced with a warning. An index this
+ * chant can't read for any other reason, or a newer contract, is left alone
+ * with a warning. Nothing here fails a job.
+ */
+import type { RunOrigin } from "../lifecycle/release-ledger.js";
+import type { CommandContext } from "../cli/registry.js";
+import { type ReportGet, type ReportPut, type ReportTarget } from "../pr-report-url.js";
+export declare const CI_RUN_INDEX_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json";
+export declare const CI_RUN_INDEX_CONTRACT = 1;
+/** The first chant that writes the index. */
+export declare const CI_RUN_INDEX_FLOOR = "0.124.31";
+/** Where the index is kept, below the report URL. */
+export declare const CI_RUN_INDEX_KEY = "runs/index.json";
+/** How many entries the index keeps unless told otherwise. */
+export declare const CI_RUN_INDEX_LIMIT = 200;
+/** One job the runner ran. */
+export interface CiRunIndexEntry {
+    job: "plan" | "apply";
+    /** The pull request, or null when the job found none. */
+    pr: number | null;
+    commit: string;
+    status: "ok" | "fail";
+    /** Why a failed job failed: the `failure.code` of its run record. */
+    failure?: {
+        code: string;
+    };
+    member?: string;
+    started: string;
+    ended: string;
+    runId: string;
+    /** The folder the job's report is under, below the report URL: `<pr>/<commit>[/<member>]`. */
+    key: string;
+    runOrigin: RunOrigin;
+    /**
+     * The runner whose key signed the run's record, or null for an unsigned
+     * run (#4156). Written by chant 0.124.32 and newer; an entry from an older
+     * chant lacks it.
+     */
+    signer?: string | null;
+    /**
+     * The code `chant ci run` exited with for the job: 0, its command's own
+     * code such as 3 for a moved plan or a waiting wave, else 1 (#4165).
+     * Written by chant 0.124.32 and newer; an entry from an older chant lacks it.
+     */
+    exitCode?: number;
+}
+export interface CiRunIndex {
+    $schema: typeof CI_RUN_INDEX_SCHEMA_ID;
+    contract: typeof CI_RUN_INDEX_CONTRACT;
+    chant: string;
+    /** When the index was last written. */
+    updated: string;
+    /** Newest first. */
+    runs: CiRunIndexEntry[];
+}
+/** The index as `text` holds it, or why it can't be used: `corrupt` is replaced, `newer` is left alone. */
+export declare function parseCiRunIndex(text: string): {
+    index: CiRunIndex;
+} | {
+    corrupt: string;
+} | {
+    newer: number;
+};
+/** `entry` at the front of `runs`, replacing an entry with its run id, cut to the newest `limit`. */
+export declare function addRunEntry(runs: readonly CiRunIndexEntry[], entry: CiRunIndexEntry, limit: number): CiRunIndexEntry[];
+/**
+ * Add `entry` to the index at `target`. Never throws: a problem is a warning
+ * and the index stays as it was, or is replaced when it was unreadable JSON.
+ */
+export declare function updateCiRunIndex(input: {
+    target: ReportTarget;
+    entry: CiRunIndexEntry;
+    limit?: number;
+    warn: (message: string) => void;
+    now?: () => Date;
+    put?: ReportPut;
+    get?: ReportGet;
+}): Promise<void>;
+/** The index at `target`, or null when none is there. Throws a line a person can read when it can't be read. */
+export declare function readCiRunIndex(target: ReportTarget, get?: ReportGet): Promise<CiRunIndex | null>;
+/** The text `chant ci runs` prints: one line per run, newest first. */
+export declare function formatCiRunIndex(index: CiRunIndex): string;
+/** `chant ci runs` (#4098): list the index at the report URL. */
+export declare function runCiRuns(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=ci-run-index.d.ts.map

package/dist/workspace/ci-run-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-run-index.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-run-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAwC,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAG3H,eAAO,MAAM,sBAAsB,0FAA0F,CAAC;AAC9H,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,6CAA6C;AAC7C,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAClD,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtB,yDAAyD;IACzD,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IACtB,qEAAqE;IACrE,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,sBAAsB,CAAC;IACvC,QAAQ,EAAE,OAAO,qBAAqB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB;AAID,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAc7G;AAED,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAEtH;AAKD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB;AAED,gHAAgH;AAChH,wBAAsB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,SAA6B,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAQzH;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAS1D;AAID,iEAAiE;AACjE,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAepE"}

package/dist/workspace/ci-run-index.js

@@ -0,0 +1,164 @@
+/**
+ * The run index (#4098, epic #4101): where the chant runner says which jobs it
+ * ran, at the `--report-url` root, for behold and the demo kiosk to find runs
+ * without a forge or a workflow file.
+ *
+ * ```
+ * <url>/runs/index.json
+ * ```
+ *
+ * One document, `ci-run-index/v1` (`ci-run-index.schema.json`). Each settled
+ * `chant ci run` job with `--report-url` set adds an entry to its front, so
+ * the newest run is first, and the list is cut to the newest `limit` entries,
+ * 200 by default. An entry's `key` is the folder the job's report went to
+ * (`reportKey`, `<pr>/<commit>`), so a reader goes from the index to
+ * `<url>/<key>/pr-<job>.json`.
+ *
+ * The update reads the index, changes it and writes it back through the same
+ * `file://` and `s3://` paths the report upload uses (pr-report-url.ts). A
+ * `file://` write goes through a temporary name and a rename. Two runners
+ * updating one index at once can lose an entry, and that is out of scope:
+ * `chant ci serve` is one host. Within one process the updates for one URL
+ * take turns, so `ci serve --max-jobs 2` does not race itself.
+ *
+ * An index that can't be parsed is replaced with a warning. An index this
+ * chant can't read for any other reason, or a newer contract, is left alone
+ * with a warning. Nothing here fails a job.
+ */
+import { formatError } from "../cli/format.js";
+import { reportUrlOf } from "./ci-report-url.js";
+import { parseReportUrl, reportGet, reportPut } from "../pr-report-url.js";
+import { readerVersion } from "./declaration.js";
+export const CI_RUN_INDEX_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json";
+export const CI_RUN_INDEX_CONTRACT = 1;
+/** The first chant that writes the index. */
+export const CI_RUN_INDEX_FLOOR = "0.124.31";
+/** Where the index is kept, below the report URL. */
+export const CI_RUN_INDEX_KEY = "runs/index.json";
+/** How many entries the index keeps unless told otherwise. */
+export const CI_RUN_INDEX_LIMIT = 200;
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/** The index as `text` holds it, or why it can't be used: `corrupt` is replaced, `newer` is left alone. */
+export function parseCiRunIndex(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (err) {
+        return { corrupt: `it is not JSON (${messageOf(err)})` };
+    }
+    if (doc === null || typeof doc !== "object" || Array.isArray(doc))
+        return { corrupt: "it is not an object" };
+    const d = doc;
+    if (typeof d.contract === "number" && d.contract > CI_RUN_INDEX_CONTRACT)
+        return { newer: d.contract };
+    if (d.contract !== CI_RUN_INDEX_CONTRACT)
+        return { corrupt: "it is not a ci-run-index document" };
+    if (!Array.isArray(d.runs))
+        return { corrupt: "it has no runs list" };
+    const runs = d.runs.filter((r) => r !== null && typeof r === "object" && typeof r.runId === "string");
+    return { index: { ...doc, runs } };
+}
+/** `entry` at the front of `runs`, replacing an entry with its run id, cut to the newest `limit`. */
+export function addRunEntry(runs, entry, limit) {
+    return [entry, ...runs.filter((r) => r.runId !== entry.runId)].slice(0, limit);
+}
+/** The turn each index URL is waiting for, so updates in one process run one after another. */
+const turns = new Map();
+/**
+ * Add `entry` to the index at `target`. Never throws: a problem is a warning
+ * and the index stays as it was, or is replaced when it was unreadable JSON.
+ */
+export function updateCiRunIndex(input) {
+    const where = `${input.target.url}/${CI_RUN_INDEX_KEY}`;
+    const put = input.put ?? reportPut(input.target);
+    const get = input.get ?? reportGet(input.target);
+    const limit = Math.max(1, Math.floor(input.limit ?? CI_RUN_INDEX_LIMIT));
+    const work = async () => {
+        let runs = [];
+        try {
+            const text = await get(CI_RUN_INDEX_KEY);
+            if (text !== null) {
+                const parsed = parseCiRunIndex(text);
+                if ("corrupt" in parsed)
+                    input.warn(`the run index at ${where} is replaced, since ${parsed.corrupt}`);
+                else if ("newer" in parsed)
+                    return input.warn(`the run index at ${where} is contract ${parsed.newer}, which this chant does not write; it is left as it is`);
+                else
+                    runs = parsed.index.runs;
+            }
+        }
+        catch (err) {
+            return input.warn(`could not read the run index at ${where}, so it is not updated: ${messageOf(err)}`);
+        }
+        const index = {
+            $schema: CI_RUN_INDEX_SCHEMA_ID,
+            contract: CI_RUN_INDEX_CONTRACT,
+            chant: readerVersion(),
+            updated: (input.now?.() ?? new Date()).toISOString(),
+            runs: addRunEntry(runs, input.entry, limit),
+        };
+        try {
+            await put(CI_RUN_INDEX_KEY, JSON.stringify(index, null, 2) + "\n", "application/json");
+        }
+        catch (err) {
+            input.warn(`could not write the run index at ${where}: ${messageOf(err)}`);
+        }
+    };
+    const previous = turns.get(where) ?? Promise.resolve();
+    const next = previous.then(work, work);
+    const settled = next.catch(() => undefined);
+    turns.set(where, settled);
+    void settled.then(() => {
+        if (turns.get(where) === settled)
+            turns.delete(where);
+    });
+    return next.catch((err) => input.warn(`could not update the run index at ${where}: ${messageOf(err)}`));
+}
+/** The index at `target`, or null when none is there. Throws a line a person can read when it can't be read. */
+export async function readCiRunIndex(target, get = reportGet(target)) {
+    const where = `${target.url}/${CI_RUN_INDEX_KEY}`;
+    const text = await get(CI_RUN_INDEX_KEY);
+    if (text === null)
+        return null;
+    const parsed = parseCiRunIndex(text);
+    if ("corrupt" in parsed)
+        throw new Error(`the run index at ${where} is unusable: ${parsed.corrupt}`);
+    if ("newer" in parsed)
+        throw new Error(`the run index at ${where} is contract ${parsed.newer}; this chant reads contract ${CI_RUN_INDEX_CONTRACT}`);
+    return parsed.index;
+}
+/** The text `chant ci runs` prints: one line per run, newest first. */
+export function formatCiRunIndex(index) {
+    if (index.runs.length === 0)
+        return "no runs in the index";
+    return index.runs
+        .map((r) => {
+        const pr = r.pr === null ? "no PR" : `PR ${r.pr}`;
+        const why = r.status === "fail" ? ` (${r.failure?.code ?? "failed"})` : "";
+        return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}${r.signer ? `  signed by ${r.signer}` : ""}`;
+    })
+        .join("\n");
+}
+const RUNS_USAGE = "chant ci runs [--report-url <s3://<bucket>/<prefix> | file://<directory>>] [--json]";
+/** `chant ci runs` (#4098): list the index at the report URL. */
+export async function runCiRuns(ctx) {
+    try {
+        // #4160: without --report-url, the declaration's ci.reportUrl.
+        const raw = await reportUrlOf(ctx.args.reportUrl, process.cwd());
+        if (!raw)
+            throw new Error("--report-url names where the index is kept, unless the workspace declares ci.reportUrl");
+        const target = parseReportUrl(raw);
+        if ("error" in target)
+            throw new Error(target.error);
+        const index = await readCiRunIndex(target);
+        if (index === null)
+            throw new Error(`there is no run index at ${target.url}/${CI_RUN_INDEX_KEY}`);
+        console.log(ctx.args.json ? JSON.stringify(index, null, 2) : formatCiRunIndex(index));
+        return 0;
+    }
+    catch (err) {
+        console.error(formatError({ message: `chant ci runs: ${messageOf(err)}`, hint: RUNS_USAGE }));
+        return 1;
+    }
+}

package/dist/workspace/ci-run-index.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json",
+  "title": "chant ci run index",
+  "description": "The runs the chant runner has run, kept at <report-url>/runs/index.json (#4098, epic #4101) so a reader outside CI finds them without a forge or a workflow file. `chant ci run` adds an entry to the front after each job settles when --report-url is set, so the list is newest first, and keeps the newest 200 entries unless --run-index-limit says otherwise. `chant ci runs --json` prints the same document. An entry's `key` is the folder the job's report is under, below the report URL. The update is a read, a change and a write of the whole file, through the same s3:// and file:// paths the report upload uses; a file:// write goes through a temporary name and a rename. Two runners updating one index at once can lose an entry. That is out of scope, because `chant ci serve` is one host. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version. Written by chant 0.124.31 and newer. Added within contract 1 at chant 0.124.32: an entry's signer (#4156) and exitCode (#4165); an entry from an older chant lacks them.",
+  "type": "object",
+  "required": ["$schema", "contract", "chant", "updated", "runs"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json" },
+    "contract": { "const": 1 },
+    "chant": { "type": "string", "description": "The chant that last wrote the index." },
+    "updated": { "type": "string", "description": "When the index was last written." },
+    "runs": {
+      "type": "array",
+      "description": "Newest first, at most the limit the writer was given (200 by default).",
+      "items": { "$ref": "#/$defs/run" }
+    }
+  },
+  "$defs": {
+    "run": {
+      "type": "object",
+      "required": ["job", "pr", "commit", "status", "started", "ended", "runId", "key", "runOrigin"],
+      "if": { "properties": { "status": { "const": "fail" } } },
+      "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
+      "properties": {
+        "job": { "enum": ["plan", "apply"] },
+        "pr": { "type": ["integer", "null"], "minimum": 1, "description": "The pull or merge request number: the one the job's report names, else --pr. null when neither has one." },
+        "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit the job ran at." },
+        "status": { "enum": ["ok", "fail"] },
+        "failure": {
+          "type": "object",
+          "required": ["code"],
+          "description": "Present when status is fail. The same code the run record's failure carries: setup-failed, build-failed, a report's refusal or status, or command-failed.",
+          "properties": { "code": { "type": "string" } }
+        },
+        "member": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "The workspace member whose pipeline the job ran for. Absent outside a member." },
+        "started": { "type": "string", "description": "ISO-8601 instant the job started." },
+        "ended": { "type": "string", "description": "ISO-8601 instant the job settled." },
+        "runId": { "type": "string", "description": "The Op run id, as in the run ledger on chant/lifecycle." },
+        "key": { "type": "string", "description": "reportKey(pr, commit): <pr>/<commit>, with /<member> after for a member, and unknown for a missing pr. The job's report is <report-url>/<key>/pr-<job>.json." },
+        "signer": { "type": ["string", "null"], "description": "Added within contract 1 by #4156, written by chant 0.124.32 and newer. The runner whose key signed the run's record, or null for an unsigned run. Signing is optional, and an unsigned run is listed like any other." },
+        "exitCode": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Added within contract 1 by #4165, written by chant 0.124.32 and newer. The code chant ci run exited with for the job: 0 for a passed job, else the command's own code when it is 1 to 255, such as 3 for a plan that moved after review or a wave waiting at its gate, else 1. A reader tells a held run from a failed one by it when the report carries no refusal. An entry from an older chant lacks it." },
+        "runOrigin": {
+          "type": "object",
+          "required": ["forge"],
+          "description": "Where the run says it ran. { forge: \"chant\" } for a job the chant runner ran. From chant 0.124.32 a forge job that runs chant ci run names the forge's run (#4156): forge github (GitHub and Forgejo) or gitlab, with repo, url, jobId and attempt when the forge gives them.",
+          "properties": { "forge": { "type": "string" }, "repo": { "type": "string" }, "url": { "type": "string" }, "jobId": { "type": "string" }, "attempt": { "type": "integer", "minimum": 1 } }
+        }
+      }
+    }
+  }
+}