dorfl 0.14.2 → 0.15.0

package/dist/ci-agent-result.d.ts

@@ -0,0 +1,151 @@
+/**
+ * **What the apply phase does with the agent job's result** (spec
+ * `ci-agent-job-without-write-token` §8 "Agent result", decision 5 of ADR
+ * `ci-agent-job-holds-no-write-token`, task `ci-split-agent-result-and-reruns`).
+ *
+ * The apply job receives `needs.agent.result` (`--agent-result`). It is part of
+ * the HOSTILE channel: `success` is only the precondition for reading the
+ * artifact, never evidence that its content is good. Every other result never
+ * reads the artifact:
+ *
+ *  - `failure`: surface the item to needs-attention (the lock is released);
+ *  - `cancelled`: GitHub reports a TIMED-OUT job as `cancelled` too (measured,
+ *    finding `github-actions-job-timeout-reported-as-cancelled`), so the apply
+ *    job reads the agent job from the Actions API ({@link detectAgentTimeout}).
+ *    A timeout surfaces; a real cancel only releases the lock; anything it
+ *    cannot read surfaces (the safe side);
+ *  - `skipped`: accepted only when the lock job said `needsAgent: false` (the
+ *    apply job then runs the deterministic rung itself); otherwise it is a
+ *    failure.
+ *
+ * This module DECIDES; each path split acts on the decision (its surface and
+ * its release differ: a task lock, an intake label).
+ */
+/** The values of `needs.<job>.result` GitHub Actions reports. */
+export declare const AGENT_JOB_RESULTS: readonly ["success", "failure", "cancelled", "skipped"];
+/** `needs.agent.result`, as the apply job receives it. */
+export type AgentJobResult = (typeof AGENT_JOB_RESULTS)[number];
+/** A malformed `--agent-result` or `--agent-timeout-minutes`. */
+export declare class AgentResultUsageError extends Error {
+    readonly name = "AgentResultUsageError";
+}
+/** Parse `--agent-result` (exactly one of {@link AGENT_JOB_RESULTS}). */
+export declare function parseAgentJobResult(raw: string): AgentJobResult;
+/** Parse `--agent-timeout-minutes` (a positive integer, the lock output). */
+export declare function parseAgentTimeoutMinutes(raw: string): number;
+/**
+ * The fragment of GitHub's timeout annotation ("The job has exceeded the maximum
+ * execution time of <duration>"), matched as a substring only.
+ */
+export declare const TIMEOUT_ANNOTATION_FRAGMENT = "exceeded the maximum execution time";
+/**
+ * The tolerance under `agentTimeoutMinutes` at which the agent job's duration
+ * already counts as a timeout: the job clock may start after `started_at`.
+ */
+export declare const TIMEOUT_TOLERANCE_MS = 60000;
+/** The most pages {@link detectAgentTimeout} reads from one listing. */
+export declare const MAX_API_PAGES = 50;
+/**
+ * One GET against the GitHub REST API: the status, the parsed JSON body and the
+ * `rel="next"` page URL from the `Link` header. Tests stub it.
+ */
+export type GithubApiGet = (url: string) => Promise<{
+    status: number;
+    body: unknown;
+    next?: string;
+}>;
+/** How a cancelled agent job ended, as far as the Actions API tells. */
+export type CancelVerdict = 
+/** The job hit its `timeout-minutes` (either signal said so). */
+{
+    kind: 'timeout';
+    why: string;
+}
+/** A real cancel (a human, or a newer run's concurrency). */
+ | {
+    kind: 'cancel';
+    why: string;
+}
+/** The API could not be read, or the job not found: treated as a timeout. */
+ | {
+    kind: 'unreadable';
+    why: string;
+};
+/** Where the Actions API reads of {@link detectAgentTimeout} go. */
+export interface ActionsRunRef {
+    /** `GITHUB_API_URL` (default `https://api.github.com`). */
+    apiUrl: string;
+    /** `GITHUB_REPOSITORY` (`owner/repo`). */
+    repository: string;
+    /** `GITHUB_RUN_ID`. */
+    runId: string;
+    /** `GITHUB_RUN_ATTEMPT`. */
+    runAttempt: string;
+}
+/**
+ * The run this apply job belongs to, from the Actions environment, or
+ * `undefined` when any part is missing (the caller then surfaces).
+ */
+export declare function actionsRunRefFromEnv(env: NodeJS.ProcessEnv): ActionsRunRef | undefined;
+/**
+ * A {@link GithubApiGet} over `fetch` authenticated with `GITHUB_TOKEN` ONLY:
+ * the job's own token, which the apply job grants `actions: read` and
+ * `checks: read`. Never `GH_TOKEN` / `DORFL_GH_TOKEN` (the write credential has
+ * no business reading this). `undefined` when `GITHUB_TOKEN` is not set.
+ */
+export declare function githubTokenApiGet(env: NodeJS.ProcessEnv): GithubApiGet | undefined;
+/**
+ * Is this job the item's agent job? Inside a called workflow the job is named
+ * `<caller job> / agent`; a workflow that is not called names it `agent`.
+ */
+export declare function isAgentJobName(name: string): boolean;
+/**
+ * Tell a timed-out agent job from a cancelled one (decision 5). Two signals,
+ * either one meaning timeout:
+ *
+ *  - an annotation of the agent job's check run containing
+ *    {@link TIMEOUT_ANNOTATION_FRAGMENT}, read across EVERY page;
+ *  - the job's `completed_at - started_at` (written by GitHub, not the agent)
+ *    reaching `agentTimeoutMinutes` minus {@link TIMEOUT_TOLERANCE_MS}.
+ *
+ * Anything it cannot establish (no token, an API error, no single agent job in
+ * this run attempt, no timestamps, no trusted timeout) is `unreadable`, which
+ * the caller surfaces. Annotation text is agent-controllable (a job can write
+ * `::error::` lines): it is only substring-matched, and NEVER copied into the
+ * verdict, a note or the output.
+ */
+export declare function detectAgentTimeout(params: {
+    get: GithubApiGet | undefined;
+    run: ActionsRunRef | undefined;
+    agentTimeoutMinutes: number | undefined;
+}): Promise<CancelVerdict>;
+/** What the apply phase does, given the agent job's result. */
+export type AgentResultDecision = 
+/** `success`: read and validate the handoff. */
+{
+    action: 'read-handoff';
+}
+/** `skipped` with `needsAgent: false`: run the deterministic rung itself. */
+ | {
+    action: 'deterministic';
+}
+/** Surface the item to needs-attention (and release the lock); no artifact read. */
+ | {
+    action: 'surface';
+    reason: string;
+}
+/** Only release the lock (a real cancel); no artifact read. */
+ | {
+    action: 'release';
+    reason: string;
+};
+/**
+ * Decide what the apply phase does with `needs.agent.result` (decision 5).
+ * `detectTimeout` is called only for `cancelled`.
+ */
+export declare function decideAgentResult(params: {
+    result: AgentJobResult;
+    needsAgent: boolean | undefined;
+    detectTimeout: () => Promise<CancelVerdict>;
+}): Promise<AgentResultDecision>;
+//# sourceMappingURL=ci-agent-result.d.ts.map

package/dist/ci-agent-result.d.ts.map

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

package/dist/ci-agent-result.js

@@ -0,0 +1,314 @@
+/**
+ * **What the apply phase does with the agent job's result** (spec
+ * `ci-agent-job-without-write-token` §8 "Agent result", decision 5 of ADR
+ * `ci-agent-job-holds-no-write-token`, task `ci-split-agent-result-and-reruns`).
+ *
+ * The apply job receives `needs.agent.result` (`--agent-result`). It is part of
+ * the HOSTILE channel: `success` is only the precondition for reading the
+ * artifact, never evidence that its content is good. Every other result never
+ * reads the artifact:
+ *
+ *  - `failure`: surface the item to needs-attention (the lock is released);
+ *  - `cancelled`: GitHub reports a TIMED-OUT job as `cancelled` too (measured,
+ *    finding `github-actions-job-timeout-reported-as-cancelled`), so the apply
+ *    job reads the agent job from the Actions API ({@link detectAgentTimeout}).
+ *    A timeout surfaces; a real cancel only releases the lock; anything it
+ *    cannot read surfaces (the safe side);
+ *  - `skipped`: accepted only when the lock job said `needsAgent: false` (the
+ *    apply job then runs the deterministic rung itself); otherwise it is a
+ *    failure.
+ *
+ * This module DECIDES; each path split acts on the decision (its surface and
+ * its release differ: a task lock, an intake label).
+ */
+/** The values of `needs.<job>.result` GitHub Actions reports. */
+export const AGENT_JOB_RESULTS = [
+    'success',
+    'failure',
+    'cancelled',
+    'skipped',
+];
+/** A malformed `--agent-result` or `--agent-timeout-minutes`. */
+export class AgentResultUsageError extends Error {
+    name = 'AgentResultUsageError';
+}
+/** Parse `--agent-result` (exactly one of {@link AGENT_JOB_RESULTS}). */
+export function parseAgentJobResult(raw) {
+    if (AGENT_JOB_RESULTS.includes(raw)) {
+        return raw;
+    }
+    throw new AgentResultUsageError(`--agent-result must be one of ${AGENT_JOB_RESULTS.join(', ')} ` +
+        `(needs.agent.result); got ${JSON.stringify(raw.slice(0, 40))}`);
+}
+/** Parse `--agent-timeout-minutes` (a positive integer, the lock output). */
+export function parseAgentTimeoutMinutes(raw) {
+    const n = /^[0-9]{1,9}$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isInteger(n) || n < 1) {
+        throw new AgentResultUsageError('--agent-timeout-minutes must be a positive integer ' +
+            '(needs.lock.outputs.agentTimeoutMinutes)');
+    }
+    return n;
+}
+/**
+ * The fragment of GitHub's timeout annotation ("The job has exceeded the maximum
+ * execution time of <duration>"), matched as a substring only.
+ */
+export const TIMEOUT_ANNOTATION_FRAGMENT = 'exceeded the maximum execution time';
+/**
+ * The tolerance under `agentTimeoutMinutes` at which the agent job's duration
+ * already counts as a timeout: the job clock may start after `started_at`.
+ */
+export const TIMEOUT_TOLERANCE_MS = 60_000;
+/** The most pages {@link detectAgentTimeout} reads from one listing. */
+export const MAX_API_PAGES = 50;
+/**
+ * The run this apply job belongs to, from the Actions environment, or
+ * `undefined` when any part is missing (the caller then surfaces).
+ */
+export function actionsRunRefFromEnv(env) {
+    const repository = env.GITHUB_REPOSITORY;
+    const runId = env.GITHUB_RUN_ID;
+    const runAttempt = env.GITHUB_RUN_ATTEMPT;
+    if (repository === undefined ||
+        !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) ||
+        runId === undefined ||
+        !/^[0-9]+$/.test(runId) ||
+        runAttempt === undefined ||
+        !/^[0-9]+$/.test(runAttempt)) {
+        return undefined;
+    }
+    const apiUrl = (env.GITHUB_API_URL ?? 'https://api.github.com').replace(/\/+$/, '');
+    return { apiUrl, repository, runId, runAttempt };
+}
+/**
+ * A {@link GithubApiGet} over `fetch` authenticated with `GITHUB_TOKEN` ONLY:
+ * the job's own token, which the apply job grants `actions: read` and
+ * `checks: read`. Never `GH_TOKEN` / `DORFL_GH_TOKEN` (the write credential has
+ * no business reading this). `undefined` when `GITHUB_TOKEN` is not set.
+ */
+export function githubTokenApiGet(env) {
+    const token = env.GITHUB_TOKEN?.trim();
+    if (token === undefined || token === '')
+        return undefined;
+    return async (url) => {
+        const res = await fetch(url, {
+            headers: {
+                accept: 'application/vnd.github+json',
+                authorization: `Bearer ${token}`,
+                'x-github-api-version': '2022-11-28',
+            },
+        });
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = undefined;
+        }
+        const link = res.headers.get('link') ?? '';
+        const next = /<([^>]+)>;\s*rel="next"/.exec(link)?.[1];
+        return { status: res.status, body, next };
+    };
+}
+/**
+ * GET every page of a listing (following `rel="next"`), handing each page's
+ * body to `onPage`. Throws on a non-200 page, on a next URL outside `apiUrl`,
+ * or past {@link MAX_API_PAGES}.
+ */
+async function eachPage(get, apiUrl, first, onPage) {
+    let url = first;
+    for (let page = 1; url !== undefined; page++) {
+        if (page > MAX_API_PAGES) {
+            throw new Error(`more than ${MAX_API_PAGES} pages`);
+        }
+        if (!url.startsWith(`${apiUrl}/`)) {
+            throw new Error('a next page points outside the API');
+        }
+        const r = await get(url);
+        if (r.status !== 200)
+            throw new Error(`HTTP ${r.status}`);
+        onPage(r.body);
+        url = r.next;
+    }
+}
+/**
+ * Is this job the item's agent job? Inside a called workflow the job is named
+ * `<caller job> / agent`; a workflow that is not called names it `agent`.
+ */
+export function isAgentJobName(name) {
+    return name === 'agent' || name.endsWith(' / agent');
+}
+/**
+ * Tell a timed-out agent job from a cancelled one (decision 5). Two signals,
+ * either one meaning timeout:
+ *
+ *  - an annotation of the agent job's check run containing
+ *    {@link TIMEOUT_ANNOTATION_FRAGMENT}, read across EVERY page;
+ *  - the job's `completed_at - started_at` (written by GitHub, not the agent)
+ *    reaching `agentTimeoutMinutes` minus {@link TIMEOUT_TOLERANCE_MS}.
+ *
+ * Anything it cannot establish (no token, an API error, no single agent job in
+ * this run attempt, no timestamps, no trusted timeout) is `unreadable`, which
+ * the caller surfaces. Annotation text is agent-controllable (a job can write
+ * `::error::` lines): it is only substring-matched, and NEVER copied into the
+ * verdict, a note or the output.
+ */
+export async function detectAgentTimeout(params) {
+    const { get, run, agentTimeoutMinutes } = params;
+    if (get === undefined) {
+        return {
+            kind: 'unreadable',
+            why: 'GITHUB_TOKEN is not set, so the agent job could not be read',
+        };
+    }
+    if (run === undefined) {
+        return {
+            kind: 'unreadable',
+            why: 'GITHUB_REPOSITORY, GITHUB_RUN_ID or GITHUB_RUN_ATTEMPT is not set, ' +
+                'so the agent job could not be read',
+        };
+    }
+    const repo = `${run.apiUrl}/repos/${run.repository}`;
+    const agents = [];
+    try {
+        await eachPage(get, run.apiUrl, `${repo}/actions/runs/${run.runId}/attempts/${run.runAttempt}/jobs?per_page=100`, (body) => {
+            const jobs = body?.jobs;
+            if (!Array.isArray(jobs))
+                throw new Error('no jobs list');
+            for (const job of jobs) {
+                if (typeof job.name !== 'string' || !isAgentJobName(job.name)) {
+                    continue;
+                }
+                if (typeof job.id !== 'number' || !Number.isSafeInteger(job.id)) {
+                    throw new Error('an agent job without an id');
+                }
+                agents.push({
+                    id: job.id,
+                    startedAt: typeof job.started_at === 'string' ? job.started_at : undefined,
+                    completedAt: typeof job.completed_at === 'string'
+                        ? job.completed_at
+                        : undefined,
+                });
+            }
+        });
+    }
+    catch (err) {
+        return {
+            kind: 'unreadable',
+            why: `the jobs of run ${run.runId} attempt ${run.runAttempt} could not be read (${errorText(err)})`,
+        };
+    }
+    if (agents.length !== 1) {
+        return {
+            kind: 'unreadable',
+            why: `run ${run.runId} attempt ${run.runAttempt} has ${agents.length} ` +
+                `jobs named '/ agent', not exactly one`,
+        };
+    }
+    const agent = agents[0];
+    // Signal 1: the duration GitHub recorded (the agent cannot write it).
+    const started = Date.parse(agent.startedAt ?? '');
+    const completed = Date.parse(agent.completedAt ?? '');
+    let durationKnown = false;
+    if (Number.isFinite(started) && Number.isFinite(completed)) {
+        durationKnown = true;
+        if (agentTimeoutMinutes !== undefined &&
+            completed - started >= agentTimeoutMinutes * 60_000 - TIMEOUT_TOLERANCE_MS) {
+            const minutes = Math.floor((completed - started) / 60_000);
+            return {
+                kind: 'timeout',
+                why: `the agent job ran ${minutes} minute(s), within a minute of its ` +
+                    `${agentTimeoutMinutes}-minute timeout`,
+            };
+        }
+    }
+    // Signal 2: GitHub's timeout annotation, on ANY page.
+    let annotated = false;
+    try {
+        await eachPage(get, run.apiUrl, `${repo}/check-runs/${agent.id}/annotations?per_page=100`, (body) => {
+            if (!Array.isArray(body))
+                throw new Error('no annotations list');
+            for (const a of body) {
+                for (const field of [a.message, a.title]) {
+                    if (typeof field === 'string' &&
+                        field.includes(TIMEOUT_ANNOTATION_FRAGMENT)) {
+                        annotated = true;
+                    }
+                }
+            }
+        });
+    }
+    catch (err) {
+        return {
+            kind: 'unreadable',
+            why: `the annotations of the agent job could not be read (${errorText(err)})`,
+        };
+    }
+    if (annotated) {
+        return {
+            kind: 'timeout',
+            why: "the agent job carries GitHub's timeout annotation",
+        };
+    }
+    if (!durationKnown) {
+        return {
+            kind: 'unreadable',
+            why: 'the agent job has no start or completion time',
+        };
+    }
+    if (agentTimeoutMinutes === undefined) {
+        return {
+            kind: 'unreadable',
+            why: 'no trusted agent timeout was given, so its duration cannot be judged',
+        };
+    }
+    return {
+        kind: 'cancel',
+        why: 'the agent job was cancelled before its timeout',
+    };
+}
+/** Only dorfl's own words: an error thrown by a listing above, or the status. */
+function errorText(err) {
+    // Our own thrown messages carry no API text; a fetch failure's message is
+    // the runtime's, never the annotation body.
+    return err instanceof Error ? err.message.slice(0, 200) : 'unknown error';
+}
+/**
+ * Decide what the apply phase does with `needs.agent.result` (decision 5).
+ * `detectTimeout` is called only for `cancelled`.
+ */
+export async function decideAgentResult(params) {
+    switch (params.result) {
+        case 'success':
+            return { action: 'read-handoff' };
+        case 'skipped':
+            if (params.needsAgent === false)
+                return { action: 'deterministic' };
+            return {
+                action: 'surface',
+                reason: 'the agent job was skipped although the lock job said the item ' +
+                    'needs an agent (treated as an agent failure); the handoff was not read',
+            };
+        case 'failure':
+            return {
+                action: 'surface',
+                reason: 'the agent job failed (see its log in the workflow run); the handoff ' +
+                    'was not read',
+            };
+        case 'cancelled': {
+            const verdict = await params.detectTimeout();
+            if (verdict.kind === 'cancel') {
+                return {
+                    action: 'release',
+                    reason: `${verdict.why}; the handoff was not read`,
+                };
+            }
+            const what = verdict.kind === 'timeout'
+                ? `the agent job timed out: ${verdict.why}`
+                : `the agent job was cancelled and it could not be told whether it ` +
+                    `timed out (${verdict.why}), so it is treated as a timeout`;
+            return { action: 'surface', reason: `${what}; the handoff was not read` };
+        }
+    }
+}
+//# sourceMappingURL=ci-agent-result.js.map

package/dist/ci-agent-result.js.map

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

package/dist/ci-handoff-apply.d.ts

@@ -0,0 +1,162 @@
+/**
+ * **The apply phase's validation of a handoff** (spec
+ * `ci-agent-job-without-write-token`, ADR `ci-agent-job-holds-no-write-token`
+ * decisions 3 and 4, task `ci-split-apply-rejects-hostile-bundle`).
+ *
+ * The apply job holds a write token and runs no agent. It reads the agent job's
+ * artifact as HOSTILE: every target, mode and policy comes from TRUSTED inputs
+ * (the lock job's outputs, the workflow inputs, the tree at `baseSha`, the
+ * arbiter), never from the artifact. {@link validateApplyHandoff} is the one
+ * unit the path splits call BEFORE any write. It either returns the validated
+ * handoff (the bundle's tip fetched to {@link INCOMING_TIP_REF} in the apply
+ * checkout, the recomputed integration mode, the ledger report) or throws a
+ * {@link HandoffRejected} whose `rule` and message name the broken rule, having
+ * written nothing from the artifact anywhere: not to the arbiter, and not even
+ * into the apply checkout's object store.
+ *
+ * How "nothing is fetched into the repository" holds: the bundle is first
+ * fetched into a throwaway QUARANTINE repository whose object store borrows the
+ * apply checkout's objects (read-only, through `objects/info/alternates`), and
+ * every history, path and size check runs there. Only an accepted bundle is
+ * then fetched into the apply checkout, with the same command.
+ *
+ * The LFS objects (decision 6, task `ci-split-handoff-lfs-objects`): the new
+ * commits' blobs are scanned for pointers in the quarantine, and every object
+ * is checked against its pointer (`ci-handoff-lfs.ts`) before the import. The
+ * push of the objects (before any ref) is the path split's first write.
+ *
+ * Out of scope here: the agent-result, lock-ownership and re-run rules (wired
+ * by the path splits).
+ */
+import type { IntegrationMode } from './config.js';
+import { type HandoffRung } from './ci-handoff-format.js';
+import { type HandoffLfsObject, type ReadHandoff } from './ci-handoff.js';
+/** The apply checkout's ref an accepted bundle's tip is fetched to. */
+export declare const INCOMING_TIP_REF = "refs/dorfl/incoming/tip";
+/** The most new commits (`tip ^<arbiter>/main`) a bundle may carry. */
+export declare const MAX_NEW_COMMITS = 200;
+/** The reason for a merge commit in the range (spec, "History"). */
+export declare const MERGE_COMMIT_REASON = "the work branch contains a merge commit; rebase it and requeue";
+/**
+ * The protected path rule a repository path falls under, or `undefined`. The
+ * fixed built-in list of decision 3 (not a config key): `.github/`,
+ * `CODEOWNERS` (root, `docs/`, `.github/`), the repository config (`dorfl.json`
+ * and its legacy dotfile, which dorfl still reads), `.lfsconfig`, and
+ * `.gitattributes` at ANY depth (a nested one sets merge attributes for its
+ * subtree just like the root one). Matched case-insensitively, so a
+ * `.GitHub/` that a case-insensitive checkout would fold into `.github/` is
+ * caught too.
+ */
+export declare function protectedPathOf(path: string): string | undefined;
+/** The trusted facts the apply job validates a handoff against. */
+export interface ApplyTrust {
+    /** The item this run carries (lock output / workflow input). */
+    item: string;
+    /** The rung the lock job classified. */
+    rung: HandoffRung;
+    /** The arbiter's `main` the lock job classified the item at. */
+    baseSha: string;
+    /** The arbiter git remote of the apply checkout. */
+    arbiter: string;
+    /** The integration mode the workflow asked for (before the recomputed rules). */
+    integrationMode: IntegrationMode;
+}
+/** A handoff that passed every rule. */
+export interface ApplyHandoff {
+    handoff: ReadHandoff;
+    /**
+     * The integration mode to land with: `merge` only when the trusted
+     * `integrationMode` is `merge` AND the untrusted-origin rule, recomputed from
+     * the task at `baseSha`, does not force `propose`.
+     */
+    mode: IntegrationMode;
+    /** Whether the untrusted-origin rule turned a trusted `merge` into `propose`. */
+    forcedPropose: boolean;
+    /** The accepted bundle, when the handoff carries one. */
+    bundle?: {
+        /** The work branch name (`workBranchRef` of the trusted item). */
+        workBranch: string;
+        /** The validated tip, now at {@link INCOMING_TIP_REF} in the apply checkout. */
+        tip: string;
+        /** The new commits (`tip ^<arbiter>/main`), newest first. */
+        newCommits: string[];
+    };
+    /**
+     * The artifact's LFS objects, each referenced by a pointer of the new
+     * commits and checked against it (size and sha256), sorted by oid. The path
+     * split pushes them before any ref.
+     */
+    lfsObjects: HandoffLfsObject[];
+    /** `work/` paths the bundle changes outside this item's own transition (propose only). */
+    ledgerOutsideItem: string[];
+    /** The PR-body section listing {@link ledgerOutsideItem}, when there are any. */
+    ledgerReport?: string;
+}
+/**
+ * The untrusted-origin build-propose rule (ADR `untrusted-origin-build-checkpoint`,
+ * `integration-core.ts`), recomputed from the task AT `baseSha` in the apply
+ * checkout, never from the bundle (whose done-move could strip the stamp).
+ * Scope as in `performIntegration`: the task BUILD transition only; CI passes
+ * no explicit `--merge`, so there is no override. Any copy of the task at
+ * `baseSha` stamped `originTrust: untrusted` forces `propose`.
+ */
+export declare function recomputeIntegrationMode(params: {
+    repo: string;
+    baseSha: string;
+    item: string;
+    integrationMode: IntegrationMode;
+    /** Whether the handoff is a task build (`integrate` on the build rung). */
+    build: boolean;
+    env?: NodeJS.ProcessEnv;
+}): {
+    mode: IntegrationMode;
+    forcedPropose: boolean;
+};
+/**
+ * The PR-body section that lists the `work/` paths a propose-mode bundle
+ * changes outside its own item (decision 3, user story 23). The path names come
+ * from the hostile bundle, so each is JSON-quoted inside a code fence longer
+ * than any backtick run, which keeps a crafted name from closing the fence or
+ * starting a heading; the list is bounded.
+ */
+export declare function renderLedgerReportSection(paths: readonly string[]): string;
+/**
+ * Validate the agent job's handoff before the apply job writes anything.
+ *
+ * `dir` is the downloaded artifact under `runnerTemp`; `repo` is the apply
+ * job's own checkout of the trusted base, whose `trust.arbiter` remote is
+ * fetched fresh here. The steps, each a rejection ({@link HandoffRejected})
+ * naming its rule:
+ *
+ * 1. the artifact (`readHandoff`): layout, sizes, schema, `item` equal to the
+ *    trusted item, an intent kind the trusted rung can produce;
+ * 2. the bundle's one ref must be `refs/heads/<workBranchRef(type, slug)>` of
+ *    the trusted item, and its prerequisites must exist in the apply checkout;
+ * 3. in the quarantine: fetch that ref only, with `transfer.fsckObjects`;
+ *    `baseSha` is an ancestor of the tip; the new set `tip ^<arbiter>/main` is
+ *    non-empty, at most {@link MAX_NEW_COMMITS} and has no merge commit; per
+ *    new commit, no protected path ({@link protectedPathOf}), no gitlink, no
+ *    symlink resolving outside the repository, no blob over the limit;
+ * 4. the `work/` ledger rule on the net change: only this item's own
+ *    transition and new `work/notes/*` files (ADRs live outside `work/`);
+ *    anything else is rejected in `merge` mode and reported in `propose` mode;
+ * 5. the LFS rule (`checkLfsObjects`): every blob the new commits add or
+ *    change that parses as a pointer (strict spec v1; a blob that only looks
+ *    like one is rejected) needs its object in `lfs/`, of exactly its size and
+ *    hashing to its oid; no object may be unreferenced; the size limit holds;
+ * 6. only then the bundle is fetched into the apply checkout at
+ *    {@link INCOMING_TIP_REF}. Nothing is written to the apply checkout's LFS
+ *    store here: the path split pushes {@link ApplyHandoff.lfsObjects} before
+ *    any ref (`pushLfsObjects`).
+ *
+ * The integration mode is recomputed ({@link recomputeIntegrationMode}) before
+ * the ledger rule, which depends on it.
+ */
+export declare function validateApplyHandoff(params: {
+    dir: string;
+    runnerTemp: string;
+    repo: string;
+    trust: ApplyTrust;
+    env?: NodeJS.ProcessEnv;
+}): ApplyHandoff;
+//# sourceMappingURL=ci-handoff-apply.d.ts.map

package/dist/ci-handoff-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-handoff-apply.d.ts","sourceRoot":"","sources":["../src/ci-handoff-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AACjD,OAAO,EAGN,KAAK,WAAW,EAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEN,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,MAAM,iBAAiB,CAAC;AAmBzB,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,uEAAuE;AACvE,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,mEACiC,CAAC;AAiBlE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAehE;AAMD,mEAAmE;AACnE,MAAM,WAAW,UAAU;IAC1B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,WAAW,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,eAAe,EAAE,eAAe,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,IAAI,EAAE,eAAe,CAAC;IACtB,iFAAiF;IACjF,aAAa,EAAE,OAAO,CAAC;IACvB,yDAAyD;IACzD,MAAM,CAAC,EAAE;QACR,kEAAkE;QAClE,UAAU,EAAE,MAAM,CAAC;QACnB,gFAAgF;QAChF,GAAG,EAAE,MAAM,CAAC;QACZ,6DAA6D;QAC7D,UAAU,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF;;;;OAIG;IACH,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,0FAA0F;IAC1F,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,eAAe,CAAC;IACjC,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAC,CAgBlD;AAMD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAqB1E;AAwUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,YAAY,CAwIf"}