@intentius/chant 0.124.31 → 0.124.33

package/dist/runner-start.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The runner-start statement (#4147): a provisioner's signed word that it
+ * started a runner for one CI job, which the job checks before it runs.
+ *
+ * A persistent self-hosted runner keeps files and processes between jobs,
+ * so a plan job that ran a pull request's code can leave something behind
+ * for the next apply. An apply job that requires this statement refuses to
+ * run, before it trades for any credentials, on a runner that no trusted
+ * provisioner says it started for this job.
+ *
+ * It differs from the Op-run statement (#4044, ./workspace/trust/op-run-statement.ts)
+ * in three ways. It is signed before the job runs, not when a run settles.
+ * The provisioner that starts the runner signs it, so the key never enters
+ * the job. And it names the CI job, run and attempt, so a statement issued
+ * for one job does not verify in another.
+ *
+ * The statement is an in-toto Statement v1 in a DSSE envelope
+ * (./workspace/trust/dsse.ts), signed with an Ed25519 key that
+ * `.chant/trust.json` lists under `runners`, whose principal holds the
+ * `runner` role there, the same keys and role a ci tag needs (#4031):
+ *
+ * - `subject`: the commit the job runs, by `digest.gitCommit`.
+ * - `predicate`: the signer's principal; `ci` with the system (`github`,
+ *   `gitlab`, `forgejo`), the repository, and the run, attempt and job ids;
+ *   `runner` with the runner's name and `singleJob: true`; and `issuedAt`.
+ *
+ * The job finds it in `CHANT_RUNNER_START` (the envelope's JSON) or in the
+ * file `CHANT_RUNNER_START_FILE` names, else in
+ * {@link DEFAULT_RUNNER_START_FILE}. The job's own ids come from the forge's
+ * variables ({@link ciJobFromEnv}).
+ *
+ * This module needs only `node:crypto` and `node:fs`, so a bundled stage can
+ * import it alone:
+ *
+ * ```ts
+ * import { verifyRunnerStartForJob } from "@intentius/chant/runner-start";
+ *
+ * const trust = JSON.parse(readFileSync(".chant/trust.json", "utf8"));
+ * const v = verifyRunnerStartForJob({ runners: trust.runners ?? [], roles: trust.roles ?? {} });
+ * if (v.status !== "verified") throw new Error(v.reason);
+ * ```
+ *
+ * `chant ci runner-start verify` and `chant ci run --require-runner-start`
+ * read the runners and roles from `.chant/trust.json` at base, which also
+ * drops a runner entry the signers file lists (./workspace/trust/policy.ts).
+ * A caller that passes trust.json's lists itself skips that check.
+ */
+import type { KeyObject } from "node:crypto";
+import { type DsseEnvelope } from "./workspace/trust/dsse.js";
+export declare const RUNNER_START_PREDICATE = "https://intentius.io/chant/runner-start/v1";
+/** The in-toto Statement v1 type, as ./workspace/trust/evidence.ts has it. */
+declare const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** The role a runner-start statement's signer must hold in `.chant/trust.json`, as for a ci tag (#4031). */
+export declare const RUNNER_START_SIGNER_ROLE = "runner";
+/** The variable that holds the statement's envelope as JSON. */
+export declare const RUNNER_START_ENV = "CHANT_RUNNER_START";
+/** The variable that names a file holding the envelope, in place of {@link DEFAULT_RUNNER_START_FILE}. */
+export declare const RUNNER_START_FILE_ENV = "CHANT_RUNNER_START_FILE";
+/** Where the job looks for the envelope when neither variable is set. */
+export declare const DEFAULT_RUNNER_START_FILE = "/run/chant/runner-start.json";
+export type CiSystem = "github" | "gitlab" | "forgejo";
+/** The CI job a runner was started for, or the job reading the statement. */
+export interface CiJobIdentity {
+    system: CiSystem;
+    /** `owner/name` on GitHub and Forgejo, the project path on GitLab. */
+    repo: string;
+    /** The run: `GITHUB_RUN_ID`, or `CI_PIPELINE_ID` on GitLab. */
+    run: string;
+    /** The run's attempt: `GITHUB_RUN_ATTEMPT`. GitLab gives a retried job a new job id, so it is always `1` there. */
+    attempt: string;
+    /** The job: `GITHUB_JOB`, the job's key in the workflow, or `CI_JOB_ID` on GitLab. */
+    job: string;
+    /** The full commit id the job runs: `GITHUB_SHA`, or `CI_COMMIT_SHA`. */
+    commit: string;
+    /**
+     * The runner's name: `RUNNER_NAME` on GitHub and Forgejo. Required there,
+     * since `GITHUB_JOB` repeats across a matrix's jobs and the runner's name
+     * tells them apart. Not compared on GitLab, where `CI_JOB_ID` is unique.
+     */
+    runner?: string;
+}
+export interface RunnerStartStatement {
+    _type: typeof STATEMENT_TYPE;
+    subject: [{
+        name: string;
+        digest: {
+            gitCommit: string;
+        };
+    }];
+    predicateType: typeof RUNNER_START_PREDICATE;
+    predicate: {
+        signer: string;
+        ci: {
+            system: CiSystem;
+            repo: string;
+            run: string;
+            attempt: string;
+            job: string;
+        };
+        runner: {
+            name?: string;
+            singleJob: true;
+        };
+        issuedAt: string;
+    };
+}
+/** A key that may sign the statement, as `.chant/trust.json` lists it under `runners`. */
+export interface RunnerStartKey {
+    principal: string;
+    /** `ssh-ed25519 <base64>`. */
+    key: string;
+}
+/** Whoever signs: the provisioner's key and the principal `.chant/trust.json` lists it for. */
+export interface RunnerStartSigner {
+    principal: string;
+    key: KeyObject;
+    publicKey: string;
+}
+/** The job the forge's variables name, or why they name none. GitHub's names are also Forgejo's; `FORGEJO_ACTIONS` or `GITEA_ACTIONS` marks Forgejo, as in ./notify.ts. */
+export declare function ciJobFromEnv(env?: Record<string, string | undefined>): {
+    ok: true;
+    job: CiJobIdentity;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The statement `signer` signs for a runner started for `job`. Throws for a job it cannot name. */
+export declare function buildRunnerStartStatement(job: CiJobIdentity, signer: string, issuedAt?: Date): RunnerStartStatement;
+/** The envelope the provisioner hands the runner, signed with its key. */
+export declare function signRunnerStart(job: CiJobIdentity, signer: RunnerStartSigner, issuedAt?: Date): DsseEnvelope;
+export type RunnerStartVerdict = {
+    status: "verified";
+    signer: string;
+    keyid: string;
+    issuedAt: string;
+    reason: string;
+} | {
+    status: "missing" | "invalid" | "untrusted" | "mismatch" | "stale";
+    reason: string;
+};
+export interface VerifyRunnerStartInput {
+    /** The envelope, as JSON text or parsed. Undefined when the job found none. */
+    envelope: unknown;
+    /** The job reading it. */
+    job: CiJobIdentity;
+    /** `runners` from `.chant/trust.json` at base. */
+    runners: readonly RunnerStartKey[];
+    /** `roles` from `.chant/trust.json` at base. */
+    roles: Readonly<Record<string, readonly string[]>>;
+    /** Refuse a statement issued longer ago than this. Default: no limit, since a statement names one job attempt. */
+    maxAgeSeconds?: number;
+    now?: Date;
+}
+/**
+ * Verify a runner-start statement for `job`: a signature by a key listed
+ * under `runners` whose principal holds the `runner` role, over a statement
+ * for this system, repository, run, attempt, job, commit and, on GitHub and
+ * Forgejo, runner. Never throws.
+ */
+export declare function verifyRunnerStart(input: VerifyRunnerStartInput): RunnerStartVerdict;
+/** The envelope's JSON the job was given: `CHANT_RUNNER_START`, else the file `CHANT_RUNNER_START_FILE` names, else {@link DEFAULT_RUNNER_START_FILE}. Undefined when there is none. */
+export declare function readRunnerStart(env?: Record<string, string | undefined>, readFile?: (path: string) => string): string | undefined;
+/**
+ * One call for a job: find its statement ({@link readRunnerStart}), name the
+ * job from the forge's variables ({@link ciJobFromEnv}) and verify one
+ * against the other ({@link verifyRunnerStart}). Never throws.
+ */
+export declare function verifyRunnerStartForJob(input: {
+    runners: readonly RunnerStartKey[];
+    roles: Readonly<Record<string, readonly string[]>>;
+    env?: Record<string, string | undefined>;
+    /** The commit the job runs, in place of the forge's variable. */
+    commit?: string;
+    readFile?: (path: string) => string;
+    maxAgeSeconds?: number;
+    now?: Date;
+}): RunnerStartVerdict;
+export {};
+//# sourceMappingURL=runner-start.d.ts.map

package/dist/runner-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-start.d.ts","sourceRoot":"","sources":["../src/runner-start.ts"],"names":[],"mappings":"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"}

package/dist/runner-start.js

@@ -0,0 +1,277 @@
+/**
+ * The runner-start statement (#4147): a provisioner's signed word that it
+ * started a runner for one CI job, which the job checks before it runs.
+ *
+ * A persistent self-hosted runner keeps files and processes between jobs,
+ * so a plan job that ran a pull request's code can leave something behind
+ * for the next apply. An apply job that requires this statement refuses to
+ * run, before it trades for any credentials, on a runner that no trusted
+ * provisioner says it started for this job.
+ *
+ * It differs from the Op-run statement (#4044, ./workspace/trust/op-run-statement.ts)
+ * in three ways. It is signed before the job runs, not when a run settles.
+ * The provisioner that starts the runner signs it, so the key never enters
+ * the job. And it names the CI job, run and attempt, so a statement issued
+ * for one job does not verify in another.
+ *
+ * The statement is an in-toto Statement v1 in a DSSE envelope
+ * (./workspace/trust/dsse.ts), signed with an Ed25519 key that
+ * `.chant/trust.json` lists under `runners`, whose principal holds the
+ * `runner` role there, the same keys and role a ci tag needs (#4031):
+ *
+ * - `subject`: the commit the job runs, by `digest.gitCommit`.
+ * - `predicate`: the signer's principal; `ci` with the system (`github`,
+ *   `gitlab`, `forgejo`), the repository, and the run, attempt and job ids;
+ *   `runner` with the runner's name and `singleJob: true`; and `issuedAt`.
+ *
+ * The job finds it in `CHANT_RUNNER_START` (the envelope's JSON) or in the
+ * file `CHANT_RUNNER_START_FILE` names, else in
+ * {@link DEFAULT_RUNNER_START_FILE}. The job's own ids come from the forge's
+ * variables ({@link ciJobFromEnv}).
+ *
+ * This module needs only `node:crypto` and `node:fs`, so a bundled stage can
+ * import it alone:
+ *
+ * ```ts
+ * import { verifyRunnerStartForJob } from "@intentius/chant/runner-start";
+ *
+ * const trust = JSON.parse(readFileSync(".chant/trust.json", "utf8"));
+ * const v = verifyRunnerStartForJob({ runners: trust.runners ?? [], roles: trust.roles ?? {} });
+ * if (v.status !== "verified") throw new Error(v.reason);
+ * ```
+ *
+ * `chant ci runner-start verify` and `chant ci run --require-runner-start`
+ * read the runners and roles from `.chant/trust.json` at base, which also
+ * drops a runner entry the signers file lists (./workspace/trust/policy.ts).
+ * A caller that passes trust.json's lists itself skips that check.
+ */
+import { readFileSync } from "node:fs";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope } from "./workspace/trust/dsse.js";
+export const RUNNER_START_PREDICATE = "https://intentius.io/chant/runner-start/v1";
+/** The in-toto Statement v1 type, as ./workspace/trust/evidence.ts has it. */
+const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** The role a runner-start statement's signer must hold in `.chant/trust.json`, as for a ci tag (#4031). */
+export const RUNNER_START_SIGNER_ROLE = "runner";
+/** The variable that holds the statement's envelope as JSON. */
+export const RUNNER_START_ENV = "CHANT_RUNNER_START";
+/** The variable that names a file holding the envelope, in place of {@link DEFAULT_RUNNER_START_FILE}. */
+export const RUNNER_START_FILE_ENV = "CHANT_RUNNER_START_FILE";
+/** Where the job looks for the envelope when neither variable is set. */
+export const DEFAULT_RUNNER_START_FILE = "/run/chant/runner-start.json";
+const FULL_COMMIT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const SYSTEMS = ["github", "gitlab", "forgejo"];
+/** The job the forge's variables name, or why they name none. GitHub's names are also Forgejo's; `FORGEJO_ACTIONS` or `GITEA_ACTIONS` marks Forgejo, as in ./notify.ts. */
+export function ciJobFromEnv(env = process.env) {
+    const need = (names) => {
+        const missing = names.filter((n) => !env[n]);
+        return missing.length > 0 ? `the job's environment does not set ${missing.join(", ")}` : undefined;
+    };
+    if (env.GITLAB_CI === "true" || env.CI_PIPELINE_ID) {
+        const gap = need(["CI_PROJECT_PATH", "CI_PIPELINE_ID", "CI_JOB_ID", "CI_COMMIT_SHA"]);
+        if (gap)
+            return { ok: false, reason: gap };
+        return { ok: true, job: { system: "gitlab", repo: env.CI_PROJECT_PATH, run: env.CI_PIPELINE_ID, attempt: "1", job: env.CI_JOB_ID, commit: env.CI_COMMIT_SHA } };
+    }
+    if (env.GITHUB_ACTIONS === "true" || env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true") {
+        const system = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true" ? "forgejo" : "github";
+        const gap = need(["GITHUB_REPOSITORY", "GITHUB_RUN_ID", "GITHUB_JOB", "GITHUB_SHA"]);
+        if (gap)
+            return { ok: false, reason: gap };
+        return {
+            ok: true,
+            job: {
+                system,
+                repo: env.GITHUB_REPOSITORY,
+                run: env.GITHUB_RUN_ID,
+                attempt: env.GITHUB_RUN_ATTEMPT || "1",
+                job: env.GITHUB_JOB,
+                commit: env.GITHUB_SHA,
+                ...(env.RUNNER_NAME ? { runner: env.RUNNER_NAME } : {}),
+            },
+        };
+    }
+    return { ok: false, reason: "this is not a GitHub, Forgejo or GitLab job: none of GITHUB_ACTIONS, FORGEJO_ACTIONS, GITEA_ACTIONS or GITLAB_CI is set" };
+}
+/** Why `job` cannot be signed for, or undefined. */
+function jobProblem(job) {
+    if (!SYSTEMS.includes(job.system))
+        return `the CI system is ${JSON.stringify(job.system)}, not github, gitlab or forgejo`;
+    for (const field of ["repo", "run", "attempt", "job"]) {
+        if (typeof job[field] !== "string" || job[field].length === 0)
+            return `the job names no ${field}`;
+    }
+    if (!FULL_COMMIT.test(job.commit))
+        return `the job's commit ${JSON.stringify(job.commit)} is not a full commit id`;
+    if (job.system !== "gitlab" && !job.runner)
+        return `a ${job.system} job needs the runner's name, since GITHUB_JOB repeats across a matrix's jobs`;
+    return undefined;
+}
+/** The statement `signer` signs for a runner started for `job`. Throws for a job it cannot name. */
+export function buildRunnerStartStatement(job, signer, issuedAt = new Date()) {
+    const problem = jobProblem(job);
+    if (problem)
+        throw new Error(`no runner-start statement: ${problem}`);
+    return {
+        _type: STATEMENT_TYPE,
+        subject: [{ name: job.commit, digest: { gitCommit: job.commit } }],
+        predicateType: RUNNER_START_PREDICATE,
+        predicate: {
+            signer,
+            ci: { system: job.system, repo: job.repo, run: job.run, attempt: job.attempt, job: job.job },
+            runner: { ...(job.runner ? { name: job.runner } : {}), singleJob: true },
+            issuedAt: issuedAt.toISOString(),
+        },
+    };
+}
+/** The envelope the provisioner hands the runner, signed with its key. */
+export function signRunnerStart(job, signer, issuedAt = new Date()) {
+    const statement = buildRunnerStartStatement(job, signer.principal, issuedAt);
+    return signEnvelope(IN_TOTO_PAYLOAD_TYPE, Buffer.from(JSON.stringify(statement), "utf8"), signer.key, signer.publicKey);
+}
+const normalise = (name) => name.normalize("NFKC").trim().toLowerCase();
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const onlyKeys = (v, keys) => Object.keys(v).every((k) => keys.includes(k));
+const isText = (v) => typeof v === "string" && v.length > 0;
+/** The statement in `raw`, or why it is not one. Strict, so a verifier never acts on a field it does not know. */
+function parseStatement(raw) {
+    if (!isObject(raw) || !onlyKeys(raw, ["_type", "subject", "predicateType", "predicate"]))
+        return "not a statement with only _type, subject, predicateType and predicate";
+    if (raw._type !== STATEMENT_TYPE)
+        return `_type is not ${STATEMENT_TYPE}`;
+    if (raw.predicateType !== RUNNER_START_PREDICATE)
+        return `predicateType is not ${RUNNER_START_PREDICATE}`;
+    const subject = raw.subject;
+    if (!Array.isArray(subject) || subject.length !== 1)
+        return "subject is not one commit";
+    const s = subject[0];
+    if (!isObject(s) || !onlyKeys(s, ["name", "digest"]) || !isObject(s.digest) || !onlyKeys(s.digest, ["gitCommit"]))
+        return "subject is not one commit";
+    if (typeof s.name !== "string" || !FULL_COMMIT.test(s.name) || s.digest.gitCommit !== s.name)
+        return "the subject is not a full commit id named by itself";
+    const p = raw.predicate;
+    if (!isObject(p) || !onlyKeys(p, ["signer", "ci", "runner", "issuedAt"]))
+        return "predicate has fields other than signer, ci, runner and issuedAt";
+    if (!isText(p.signer))
+        return "predicate.signer is missing";
+    const ci = p.ci;
+    if (!isObject(ci) || !onlyKeys(ci, ["system", "repo", "run", "attempt", "job"]))
+        return "predicate.ci has fields other than system, repo, run, attempt and job";
+    if (!SYSTEMS.includes(ci.system))
+        return "predicate.ci.system is not github, gitlab or forgejo";
+    for (const field of ["repo", "run", "attempt", "job"])
+        if (!isText(ci[field]))
+            return `predicate.ci.${field} is missing`;
+    const runner = p.runner;
+    if (!isObject(runner) || !onlyKeys(runner, ["name", "singleJob"]) || runner.singleJob !== true)
+        return "predicate.runner does not say singleJob: true";
+    if (runner.name !== undefined && !isText(runner.name))
+        return "predicate.runner.name is not a name";
+    if (!isText(p.issuedAt) || Number.isNaN(Date.parse(p.issuedAt)))
+        return "predicate.issuedAt is not a time";
+    return raw;
+}
+/**
+ * Verify a runner-start statement for `job`: a signature by a key listed
+ * under `runners` whose principal holds the `runner` role, over a statement
+ * for this system, repository, run, attempt, job, commit and, on GitHub and
+ * Forgejo, runner. Never throws.
+ */
+export function verifyRunnerStart(input) {
+    const { job } = input;
+    const what = `the ${job.system} job ${job.job} of run ${job.run} (attempt ${job.attempt})`;
+    if (input.envelope === undefined || input.envelope === null || input.envelope === "") {
+        return { status: "missing", reason: `${what} has no runner-start statement: no provisioner says this runner was started for it` };
+    }
+    let envelope = input.envelope;
+    if (typeof envelope === "string") {
+        try {
+            envelope = JSON.parse(envelope);
+        }
+        catch {
+            return { status: "invalid", reason: `${what}: the runner-start statement is not JSON` };
+        }
+    }
+    const v = verifyEnvelope(envelope, input.runners);
+    if (!v.ok)
+        return { status: v.code === "envelope-untrusted" ? "untrusted" : "invalid", reason: `${what}: ${v.reason}` };
+    if (!(input.roles[RUNNER_START_SIGNER_ROLE] ?? []).some((p) => normalise(p) === normalise(v.principal))) {
+        return { status: "untrusted", reason: `${what}: the statement is signed by ${v.principal}'s key, and ${v.principal} holds no ${RUNNER_START_SIGNER_ROLE} role in .chant/trust.json at base` };
+    }
+    if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE)
+        return { status: "invalid", reason: `${what}: 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: `${what}: the statement's payload is not JSON` };
+    }
+    const parsed = parseStatement(raw);
+    if (typeof parsed === "string")
+        return { status: "invalid", reason: `${what}: the payload is not a ${RUNNER_START_PREDICATE} statement: ${parsed}` };
+    const p = parsed.predicate;
+    if (p.signer !== v.principal)
+        return { status: "invalid", reason: `${what}: the statement names signer ${JSON.stringify(p.signer)}, but ${v.principal}'s key signed it` };
+    const differs = [];
+    if (p.ci.system !== job.system)
+        differs.push(`it is for a ${p.ci.system} job`);
+    if (p.ci.repo !== job.repo)
+        differs.push(`it is for repository ${p.ci.repo}`);
+    if (p.ci.run !== job.run)
+        differs.push(`it is for run ${p.ci.run}`);
+    if (p.ci.attempt !== job.attempt)
+        differs.push(`it is for attempt ${p.ci.attempt}`);
+    if (p.ci.job !== job.job)
+        differs.push(`it is for job ${p.ci.job}`);
+    const commit = parsed.subject[0].name;
+    if (commit !== job.commit)
+        differs.push(`it is for commit ${commit.slice(0, 12)}, and the job runs ${job.commit.slice(0, 12)}`);
+    if (job.system !== "gitlab") {
+        if (!p.runner.name)
+            differs.push("it names no runner, and a job id alone does not tell a matrix's jobs apart");
+        else if (!job.runner)
+            differs.push(`it is for runner ${p.runner.name}, and the job's environment names no runner (RUNNER_NAME)`);
+        else if (p.runner.name !== job.runner)
+            differs.push(`it is for runner ${p.runner.name}, and this is ${job.runner}`);
+    }
+    if (differs.length > 0)
+        return { status: "mismatch", reason: `${what}: the runner-start statement signed by ${v.principal} is for another job: ${differs.join("; ")}` };
+    if (input.maxAgeSeconds !== undefined) {
+        const age = ((input.now ?? new Date()).getTime() - Date.parse(p.issuedAt)) / 1000;
+        if (age > input.maxAgeSeconds)
+            return { status: "stale", reason: `${what}: the runner-start statement was issued ${Math.round(age)}s ago, more than ${input.maxAgeSeconds}s` };
+    }
+    return { status: "verified", signer: v.principal, keyid: v.keyid, issuedAt: p.issuedAt, reason: `runner started for this job, signed by ${v.principal} (${RUNNER_START_SIGNER_ROLE})` };
+}
+/** The envelope's JSON the job was given: `CHANT_RUNNER_START`, else the file `CHANT_RUNNER_START_FILE` names, else {@link DEFAULT_RUNNER_START_FILE}. Undefined when there is none. */
+export function readRunnerStart(env = process.env, readFile = (p) => readFileSync(p, "utf8")) {
+    const inline = env[RUNNER_START_ENV];
+    if (inline)
+        return inline;
+    try {
+        return readFile(env[RUNNER_START_FILE_ENV] || DEFAULT_RUNNER_START_FILE);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One call for a job: find its statement ({@link readRunnerStart}), name the
+ * job from the forge's variables ({@link ciJobFromEnv}) and verify one
+ * against the other ({@link verifyRunnerStart}). Never throws.
+ */
+export function verifyRunnerStartForJob(input) {
+    const env = input.env ?? process.env;
+    const named = ciJobFromEnv(env);
+    if (!named.ok)
+        return { status: "missing", reason: `no job to check a runner-start statement for: ${named.reason}` };
+    const job = input.commit ? { ...named.job, commit: input.commit } : named.job;
+    return verifyRunnerStart({
+        envelope: readRunnerStart(env, input.readFile),
+        job,
+        runners: input.runners,
+        roles: input.roles,
+        ...(input.maxAgeSeconds !== undefined ? { maxAgeSeconds: input.maxAgeSeconds } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+}

package/dist/ts-loader.d.ts

@@ -18,14 +18,31 @@
  *
  * Run from source (the repository's `bin/chant` through tsx, vitest), this
  * module is itself TypeScript, the TypeScript loader is already there, and
- * both functions do nothing.
+ * both functions do nothing, except that {@link installCompiledCli} resolves
+ * chant's packages to their source (#3981, {@link installSourceResolution}).
  */
 /**
  * Called once by the CLI's `main()`. Compiled, it records that TypeScript
- * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
- * source it does nothing.
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect. From
+ * source it installs {@link installSourceResolution}.
  */
 export declare function installCompiledCli(): void;
+/**
+ * #3981 — the compiled module for a lexicon's `src/*.ts`: `<lexicon>/dist/*.js`
+ * when it exists, as a URL, else `undefined`. A lexicon ships both, and its
+ * exports name the compiled one; fold reads a composite from the source, and
+ * an import that source makes must land on the module the plugin and the
+ * project already loaded, with no TypeScript loader.
+ */
+export declare function lexiconCompiledTwin(url: string): string | undefined;
+/**
+ * #3981 — the `development` target a chant package's `exports` give
+ * `specifier`, found from `parentPath`'s directory up through each
+ * `node_modules`, or `undefined` when there is none or its file does not
+ * exist. Reads exact keys and single-`*` patterns, the shapes chant's
+ * packages use; anything else is left to Node.
+ */
+export declare function chantPackageSourceTarget(specifier: string, parentPath: string): string | undefined;
 /**
  * Register tsx for the ESM and CommonJS loaders, once, before importing
  * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
@@ -34,13 +51,30 @@ export declare function installCompiledCli(): void;
  * CommonJS hook from source knows not to add a second one.
  */
 export declare function ensureTypeScriptLoader(): boolean;
+/**
+ * #3981 — register tsx only when the module about to be imported is not
+ * JavaScript. `pathOrUrl` is the resolved module, a path or a file URL. A
+ * compiled lexicon (`dist/*.js`) imports with plain node, so a command that
+ * loads only compiled modules never pays for tsx's hooks thread. A `.ts`
+ * module, or one with no extension, registers tsx as before. Returns what
+ * {@link ensureTypeScriptLoader} does, or whether tsx is already registered
+ * when the module is JavaScript.
+ */
+export declare function ensureTypeScriptLoaderFor(pathOrUrl: string): boolean;
+/**
+ * #3981 — whether a caller about to import a module of unknown kind should
+ * resolve it first: true only in the compiled CLI before tsx is registered.
+ * From source, and once tsx is in, every module loads either way.
+ */
+export declare function typeScriptLoaderPending(): boolean;
 /**
  * The source directory for a module of chant's own: `dirname` of `moduleUrl`
  * from source, and the matching directory under `<package>/src` when the
  * module runs from `<package>/dist`. The sandbox drivers hand chant's own
  * modules to esbuild by path, and must name the TypeScript source the
  * project's own `@intentius/chant/*` imports resolve to. String arithmetic
- * only: no filesystem access, so it is safe inside a sandboxed child.
+ * only: no filesystem access, so it is safe inside a sandboxed child. The
+ * same mapping as {@link moduleSourceDir}, which lexicons use.
  */
 export declare function chantSourceDir(moduleUrl: string): string;
 //# sourceMappingURL=ts-loader.d.ts.map

package/dist/ts-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-loader.d.ts","sourceRoot":"","sources":["../src/ts-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAoCH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAwBzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAShD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOxD"}
+{"version":3,"file":"ts-loader.d.ts","sourceRoot":"","sources":["../src/ts-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAqCH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CA+BzC;AAkCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnE;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA0ClG;AAoCD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAShD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAGjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD"}