dorfl 0.14.2 → 0.15.0

package/dist/ci-phase-build.d.ts

@@ -0,0 +1,178 @@
+/**
+ * **The build path split into the three CI phases** (spec
+ * `ci-agent-job-without-write-token` §3 build row and §8, ADR
+ * `ci-agent-job-holds-no-write-token`, tasks `ci-split-build-path` and
+ * `ci-split-build-path-non-integrate-intents`).
+ *
+ * `advance task:<slug>` / `do <slug>` with `--phase` run ONE of three halves of
+ * the one build pipeline (`performDo`), never a second implementation:
+ *
+ *  - **lock** ({@link performBuildLockPhase}): fetch `<arbiter>/main` (its tip
+ *    is `baseSha`, and the tree the item is classified in, never the run's
+ *    commit); claim (`acquireItemLock`, `action: implement`); publish
+ *    `acquired`, `needsAgent`, `rung`, `baseSha`, `lockSha`, `continueTip`,
+ *    `handoffName` (it carries `github.run_attempt`, so a "Re-run all jobs"
+ *    attempt never collides with an earlier attempt's artifact) and
+ *    `agentTimeoutMinutes` (from the config at `baseSha`). An item that is not
+ *    claimable at `baseSha` (it already advanced, or its lock is held) is a
+ *    no-op that writes nothing.
+ *  - **agent** ({@link performBuildAgentPhase}): check, read-only, that the lock
+ *    ref still equals `lockSha`, then run `performDo` without its claim under
+ *    the phase recorder: the continue rebase (LOCAL only, decision 7), the
+ *    build agent, the STOP and deadline detection, the gate, the Gate-2 review,
+ *    the done-move commit, the local rebase and the fresh-worktree gate run
+ *    exactly as today, and the pipeline halts at its first write, which names
+ *    the intent handed over ({@link handOverHalt}):
+ *      - the land half (`integrationLand.land`): `integrate`, with the
+ *        work-branch bundle, the PR title and body and the Gate-2 review prose;
+ *      - a needs-attention bounce (red gate, blocked review, rebase conflict):
+ *        `needs-attention`, the wip committed locally and bundled;
+ *      - the deadline checkpoint's branch save: `deadline-checkpoint`, the
+ *        checkpoint commit bundled;
+ *      - the agent's deliberate STOP: `stop`; an agent failure: `agent-failed`
+ *        (both with the wip bundled, when there is any).
+ *  - **apply** ({@link performBuildApplyPhase}): refuse to write unless the
+ *    lock ref still equals `lockSha` (so a "Re-run failed jobs" of a finished
+ *    run writes nothing); act on the agent job's result first (task
+ *    `ci-split-agent-result-and-reruns`): anything but `success` never reads
+ *    the handoff, and surfaces the item (failure, timeout, an unexpected skip)
+ *    or only releases the lock (a real cancel); validate the handoff as hostile
+ *    (`validateApplyHandoff`); push the handoff's Git LFS objects before any
+ *    ref, for every intent (decision 6, `pushLfsObjects`); when the lock job saw a kept branch, push the
+ *    bundle's tip with a lease on that `continueTip` first (decision 7; a
+ *    stale lease writes nothing); then resume at the write half of the intent:
+ *    the land half (`landIntegration`, the unchanged compare-and-swap loop, then
+ *    the review comment), the needs-attention route, `routeDeadlineCheckpoint`
+ *    (with `maxAutoCheckpoints` from the config at `baseSha`),
+ *    `saveAgentStop` or `saveAgentFailure`. Every lock release in the apply
+ *    phase is leased on `lockSha` (`leaseLockReleases`), and the lock is
+ *    released once the work is durably on `main` (a propose PR keeps it held,
+ *    exactly as `complete` does today).
+ */
+import { type HandoffRecord } from './ci-handoff-format.js';
+import type { LockOutputs } from './ci-lock-outputs.js';
+import type { AgentJobResult, GithubApiGet } from './ci-agent-result.js';
+import { type DoOptions } from './do.js';
+import { type IntegrationCoreResult } from './integration-core.js';
+import type { Phase } from './phase.js';
+/** The verb a build phase runs under (they classify the argument differently). */
+export type BuildPhaseVerb = 'do' | 'advance';
+/** Options of a build phase run: the `do` pipeline's options plus the phase inputs. */
+export interface BuildPhaseOptions extends DoOptions {
+    /** Which of the three jobs this process is. */
+    phase: Phase;
+    /** `do <slug>` or `advance task:<slug>`. */
+    verb: BuildPhaseVerb;
+    /**
+     * The handoff directory: the agent phase writes the artifact here (it must be
+     * empty or absent); the apply phase reads it (it must be under
+     * {@link runnerTemp}).
+     */
+    handoffDir?: string;
+    /** `$RUNNER_TEMP` (the apply phase); defaults to the env's. */
+    runnerTemp?: string;
+    /** The lock job's outputs (agent / apply); defaults to `DORFL_LOCK_OUTPUTS`. */
+    lockOutputs?: LockOutputs;
+    /** `github.run_attempt` (the lock phase names the artifact with it); default the env's, else 1. */
+    runAttempt?: string;
+    /** The `$GITHUB_OUTPUT` file the lock phase appends to; default the env's. */
+    githubOutput?: string;
+    /** The merge-mode CAS-loop jitter (tests pass 0). */
+    mergeJitterMs?: number;
+    /**
+     * apply: `needs.agent.result` (`--agent-result`), REQUIRED. Only `success`
+     * reads the handoff (decision 5, task `ci-split-agent-result-and-reruns`).
+     */
+    agentResult?: AgentJobResult;
+    /**
+     * apply: the agent job's timeout (`--agent-timeout-minutes`, the trusted
+     * lock output); defaults to the lock outputs' `agentTimeoutMinutes`.
+     */
+    agentTimeoutMinutes?: number;
+    /** apply: the Actions API reader (tests stub it); default `fetch` with `GITHUB_TOKEN`. */
+    actionsApi?: GithubApiGet;
+}
+/** How a build phase run ended. */
+export type BuildPhaseOutcome = 
+/** lock: the item is claimed; the agent phase runs next. */
+'locked'
+/** lock: nothing to do at the arbiter's `main` (not claimable, or not a build). */
+ | 'no-op'
+/** lock: another run holds the item's lock. */
+ | 'lost'
+/** agent / apply: the lock ref no longer equals `lockSha`; nothing was done. */
+ | 'stale-lock'
+/** agent: the handoff was written (see `intent`). */
+ | 'handed-over'
+/** apply: the work landed on `main` and the lock was released. */
+ | 'landed'
+/** apply: the branch was pushed (and a PR requested); the lock stays held. */
+ | 'proposed'
+/** apply: the item was surfaced to needs-attention. */
+ | 'surfaced'
+/** apply: surfacing the item did not land on the arbiter (it stays locked). */
+ | 'surface-unmoved'
+/** apply: a deadline checkpoint was saved and the lock released to continue. */
+ | 'auto-continued'
+/** apply: the agent job was cancelled (not timed out); the lock was only released. */
+ | 'released'
+/** apply: the cancelled agent job's leased lock release was refused. */
+ | 'release-refused'
+/**
+ * apply: the kept work branch moved on the arbiter since the lock job saw it
+ * (`continueTip`), so the leased continue push was refused; nothing was written.
+ */
+ | 'stale-lease'
+/** apply: the handoff broke a rule; nothing from it was written. */
+ | 'rejected'
+/** A usage or environment problem, or a path this task does not split yet. */
+ | 'usage-error';
+/** The result of one build phase run. */
+export interface BuildPhaseResult {
+    /**
+     * The job's exit code: a HANDLED outcome is 0 (a surface that landed, a
+     * rejected handoff that was surfaced, a lock lost to another run, a stale
+     * lock on a re-run); only an unhandled one is non-zero. See "A handled
+     * outcome is green" in `ci-phase-driver.ts`.
+     */
+    exitCode: 0 | 1 | 2 | 3;
+    outcome: BuildPhaseOutcome;
+    /**
+     * The result line: the CLI prints it (`>> ` or `error: `), so the phase does
+     * NOT also `note` it (each line appears once in the job log).
+     */
+    message: string;
+    slug?: string;
+    /** lock: the facts published. */
+    lockOutputs?: LockOutputs;
+    /** agent: the handed-over intent kind. */
+    intent?: HandoffRecord['intent']['kind'];
+    /** apply: the land half's result, when it ran. */
+    land?: IntegrationCoreResult;
+}
+/**
+ * Run one phase of the build path. The CLI calls this for `do <slug> --phase`
+ * and `advance task:<slug> --phase`.
+ */
+export declare function performBuildPhase(options: BuildPhaseOptions): Promise<BuildPhaseResult>;
+/**
+ * The lock phase: classify the item at the arbiter's `main`, claim it and
+ * publish the trusted facts. Runs no agent and no repository code. An item that
+ * already advanced (not claimable at `baseSha`), or whose lock another run
+ * holds, is refused BEFORE any write.
+ */
+export declare function performBuildLockPhase(options: BuildPhaseOptions): Promise<BuildPhaseResult>;
+/**
+ * The agent phase: after a read-only lock-ownership check, run the build
+ * pipeline (`performDo`, without its claim) under the phase recorder, halt at
+ * the first write, and write the handoff. Holds a read-only token: it never
+ * writes to the arbiter.
+ */
+export declare function performBuildAgentPhase(options: BuildPhaseOptions): Promise<BuildPhaseResult>;
+/**
+ * The apply phase: check the lock is still this run's, validate the handoff as
+ * hostile, then resume the build at the intent's write half. Runs no agent and
+ * no repository code; every write goes through dorfl's seams.
+ */
+export declare function performBuildApplyPhase(options: BuildPhaseOptions): Promise<BuildPhaseResult>;
+//# sourceMappingURL=ci-phase-build.d.ts.map

package/dist/ci-phase-build.d.ts.map

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