@ever-works/github-actions-build-plugin 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1474 @@
+import { BuildValue, JsonSchema, IBuildPlugin, PluginCategory, BuildStrategy, PluginContext, BuildAuth, PluginManifest, PrepareRepositoryInput, RepositoryWriter, PrepareRepositoryResult, StartBuildInput, BuildRef, BuildSnapshot, AppBuildBlock, RepositoryWriteErrorCode } from '@ever-works/plugin';
+import { AppBuildBlockedReason, AppBuildKind, AppBuildRunnerClass, APP_BUILD_GENERATOR_VERSION } from '@ever-works/contracts';
+import sodiumType from 'libsodium-wrappers';
+
+/**
+ * APW-05 T12 — the narrow Actions API this plugin needs, and nothing else.
+ *
+ * ## Why a port, when `octokit` is already a dependency
+ *
+ * The same reason `RepositorySecretPort` is one (`repo/secret-sync.ts:58`): a
+ * fake is a few lines, so every rule in `run-correlator.ts` and
+ * `run-observer.ts` — the adoption window, the minutes rounding, "only the
+ * `build` job decides status" — is provable against recorded GitHub shapes
+ * without a socket, a token or a recorded-cassette harness. The port is the
+ * seam; {@link octokitActionsRunsPort} is the one implementation, and it is a
+ * thin call-through with no logic of its own to test.
+ *
+ * Octokit rather than hand-rolled `fetch`: it is the official SDK, it is already
+ * in this package's dependencies, and it handles the redirect-following that
+ * `GET actions/jobs/{id}/logs` needs (plan §4.8's logs tail).
+ *
+ * ## Shapes are the subset this plugin reads
+ *
+ * Each interface below names only the fields the correlator, the observer or the
+ * artifact reader actually use. That is deliberate: a wider type would invite a
+ * reader to assume a field is handled when nothing reads it, and GitHub's run
+ * payload is large enough that "the fields we use" is genuinely useful
+ * documentation.
+ */
+/** One workflow run, as this plugin reads it (`GET /repos/{o}/{r}/actions/runs/{id}`). */
+interface ActionsRun {
+    readonly id: number;
+    /** `queued` · `in_progress` · `completed` — GitHub's own vocabulary, mapped by the observer. */
+    readonly status: string | null;
+    readonly conclusion: string | null;
+    readonly run_attempt?: number | null;
+    /** What the generated workflow's `run-name:` produced — the correlation key (plan §4.8). */
+    readonly display_title?: string | null;
+    readonly name?: string | null;
+    readonly event?: string | null;
+    readonly head_branch?: string | null;
+    readonly head_sha?: string | null;
+    readonly html_url?: string | null;
+    readonly created_at?: string | null;
+    readonly run_started_at?: string | null;
+    readonly updated_at?: string | null;
+    readonly pull_requests?: ReadonlyArray<{
+        readonly number?: number | null;
+    }> | null;
+}
+/** One job of a run (`GET /repos/{o}/{r}/actions/runs/{id}/jobs`). */
+interface ActionsJob {
+    readonly id: number;
+    readonly name: string;
+    readonly status?: string | null;
+    readonly conclusion?: string | null;
+    readonly started_at?: string | null;
+    readonly completed_at?: string | null;
+    readonly html_url?: string | null;
+    readonly labels?: readonly string[] | null;
+    readonly steps?: ReadonlyArray<{
+        readonly name?: string | null;
+        readonly number?: number | null;
+        readonly conclusion?: string | null;
+    }> | null;
+}
+/** One artifact of a run (`GET /repos/{o}/{r}/actions/runs/{id}/artifacts`). */
+interface ActionsArtifact {
+    readonly id: number;
+    readonly name: string;
+    readonly size_in_bytes?: number | null;
+    readonly expired?: boolean | null;
+}
+/** The repository coordinates every call below takes. */
+interface ActionsRepositoryRef {
+    readonly owner: string;
+    readonly repo: string;
+}
+/**
+ * The Actions operations APW-05 T12 needs.
+ *
+ * Every method may reject; the plugin turns a rejection into a throw, never into
+ * a `null` "no such run" — those are different answers and the contract
+ * (`IBuildPlugin.getBuild`) says so in its own docstring.
+ */
+interface ActionsRunsPort {
+    /**
+     * `POST /repos/{o}/{r}/actions/workflows/{file}/dispatches` — 204, no body.
+     *
+     * GitHub answers a dispatch with no run id: the run is found afterwards, by
+     * `display_title`, which is what {@link ActionsRunsPort.listWorkflowRuns} and
+     * the correlator are for.
+     */
+    dispatchWorkflow(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly workflowFile: string;
+        readonly ref: string;
+        readonly inputs: Record<string, string>;
+    }): Promise<void>;
+    /** `GET /repos/{o}/{r}/actions/workflows/{file}/runs`, newest first. */
+    listWorkflowRuns(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly workflowFile: string;
+        readonly perPage: number;
+        readonly headSha?: string;
+        readonly event?: string;
+    }): Promise<readonly ActionsRun[]>;
+    /** `GET /repos/{o}/{r}/actions/runs/{id}`. `null` when GitHub answers 404. */
+    getWorkflowRun(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly runId: number;
+    }): Promise<ActionsRun | null>;
+    /** `GET /repos/{o}/{r}/actions/runs/{id}/jobs` (all attempts of the latest run attempt). */
+    listRunJobs(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly runId: number;
+    }): Promise<readonly ActionsJob[]>;
+    /** `POST /repos/{o}/{r}/actions/runs/{id}/cancel`. A run that is already finished is not an error. */
+    cancelWorkflowRun(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly runId: number;
+    }): Promise<void>;
+    /** `GET /repos/{o}/{r}/actions/runs/{id}/artifacts`. */
+    listRunArtifacts(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly runId: number;
+    }): Promise<readonly ActionsArtifact[]>;
+    /**
+     * `GET /repos/{o}/{r}/actions/artifacts/{id}/zip`, following the redirect.
+     *
+     * Answers the raw zip bytes. The caller enforces the size cap BEFORE
+     * unzipping (plan §4.8: "≤ 64 KB, refuse larger") — this port does not,
+     * because a port that silently truncated would make the cap untestable.
+     */
+    downloadArtifactZip(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly artifactId: number;
+    }): Promise<Uint8Array>;
+    /**
+     * `GET /repos/{o}/{r}/actions/jobs/{id}/logs`, following the redirect, asking
+     * for at most the last `maxBytes` with a `Range` header (plan §4.8).
+     *
+     * **Optional, and the only optional member of this port.** A caller whose
+     * token cannot read logs — or an adapter written before this landed — still
+     * gets a classified failure (`unknown`) rather than a thrown observation,
+     * which is why {@link readJobLogTail} probes for it instead of requiring it.
+     *
+     * `partial` reports whether the server honoured the range (`206`) rather than
+     * answering the whole body (`200`). The reader uses it to decide whether to
+     * drop the first line: a byte range almost never starts on a line boundary.
+     *
+     * `null` is "there is no log" — an expired one, or a job that never ran.
+     */
+    downloadJobLogTail?(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly jobId: number;
+        readonly maxBytes: number;
+    }): Promise<{
+        readonly bytes: Uint8Array;
+        readonly partial: boolean;
+    } | null>;
+}
+
+/** What {@link checkImageAccess} answers — the plugin's `ImageAccessResult`, plus nothing. */
+interface GhcrAccessResult {
+    readonly visibility: 'public' | 'private' | 'unknown';
+    readonly readable: boolean;
+    readonly tokenScopesOk?: boolean;
+    readonly tokenExpiresAt?: string | null;
+    readonly digest?: string;
+}
+/**
+ * The one HTTP seam, so every rule here is provable without a socket.
+ *
+ * `json()` is read only from `ghcr.io/token`'s 200 answer — the one body this
+ * module needs; the real `fetch` `Response` satisfies the shape as it is.
+ */
+type GhcrFetch = (url: string, init: {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly redirect: 'manual';
+}) => Promise<{
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}>;
+
+/**
+ * APW-05 T10 — build values in, sealed repository secrets out (plan §4.7, §4.10).
+ *
+ * ## What this file is, and what it is not
+ *
+ * It is the **only** place a build value becomes a repository secret, and the only
+ * place one is deleted. It is not a store: the value lives in the caller's memory,
+ * inside one sealed box, and in the `PUT` body — never in a return value, never in
+ * a log line, never in a thrown message. The three refusals below name things and
+ * counts, never values, because a refusal travels into `blockedReason` detail,
+ * Activity rows and telemetry (plan §9.1: "counters and identifiers only").
+ *
+ * ## The seals, and the sequence that must not drift
+ *
+ * `setActionSecret` in the github plugin
+ * (`packages/plugins/github/src/github-actions.service.ts:49-76`) is the pattern:
+ * validate the name, `await _sodium.ready`, `from_base64` the repository public
+ * key, `from_string` the value, `crypto_box_seal`, `to_base64`, `PUT` with
+ * `key_id`. This file repeats it exactly — the public key is fetched **once** for
+ * the whole batch, and every value is sealed with that one key before any `PUT`.
+ *
+ * The name rule is the same one the github plugin applies
+ * (`/^[A-Z_][A-Z0-9_]{0,254}$/`, never `GITHUB_`): GitHub itself rejects anything
+ * else, and a name that reaches GitHub is a name that already left the process.
+ * An invalid `EW_<NAME>` cannot come from APW-07's resolver (`^[A-Z_][A-Z0-9_]{0,127}$`
+ * env names), so it throws rather than blocking a Build — a programming error, not
+ * a user's mistake.
+ *
+ * ## The four refusals (plan §4.7:914–917, §4.10:1030–1033)
+ *
+ * | Condition                                                  | `blocked.reason`        | detail            |
+ * | ---------------------------------------------------------- | ----------------------- | ----------------- |
+ * | more than {@link APP_BUILD_MAX_VALUES} values               | `tooManyBuildValues`    | `{ count, max }`  |
+ * | a value over {@link APP_BUILD_SECRET_MAX_BYTES} bytes       | `buildValueTooLarge`    | `{ name }` only   |
+ * | an env name mapping onto `EW_VERIFY__PROMPTED`              | `buildValueNameReserved`| `{ name }`        |
+ * | GitHub answers the repository secret limit                  | `secretLimitReached`    | `{}`              |
+ *
+ * ## Removal is set arithmetic, and it is deliberately narrow
+ *
+ * The delete set is exactly `previouslyWrittenSecretNames` **minus** the names
+ * this call wrote. A name that was never written by the platform is never deleted,
+ * whatever it looks like — including one that starts with `EW_`, which is how an
+ * owner's own repository secret survives a preparation (FR-18).
+ *
+ * A DELETE that GitHub answers with 404 counts as removed: the name is already
+ * gone (an owner deleted it by hand, or an earlier preparation deleted it and
+ * failed before its row was written), and FR-18 is unaffected because the delete
+ * set is still only names the platform wrote. Throwing instead would leave the
+ * name on the row and fail every later preparation on the same 404, forever. A
+ * 404 from the public-key fetch or a `PUT` is NOT tolerated — there it means the
+ * repository itself is gone or not visible.
+ */
+/** The three repository-secret operations this sync needs, and nothing else (a fake is four lines). */
+interface RepositorySecretPort {
+    /** The repository's Actions public key — fetched once per operation (plan §4.7:916). */
+    getRepoPublicKey(): Promise<{
+        readonly key_id: string;
+        readonly key: string;
+    }>;
+    putRepoSecret(input: {
+        readonly name: string;
+        readonly encryptedValue: string;
+        readonly keyId: string;
+    }): Promise<void>;
+    deleteRepoSecret(input: {
+        readonly name: string;
+    }): Promise<void>;
+}
+/** Names and counts only. A logger that receives a value is a leak, and the spec proves it does not. */
+interface SecretSyncLogger {
+    debug?(message: string, meta?: Record<string, unknown>): void;
+    info?(message: string, meta?: Record<string, unknown>): void;
+    warn?(message: string, meta?: Record<string, unknown>): void;
+    error?(message: string, meta?: Record<string, unknown>): void;
+}
+/** What one build-value sync did. */
+interface BuildValueSyncResult {
+    /** The `EW_<NAME>` secrets written, in the order they were written. */
+    readonly secretsWritten: readonly string[];
+    /** The previously written names deleted, because nothing references them any more. */
+    readonly secretsRemoved: readonly string[];
+    /** `sha256(sorted (name, fingerprint))` over the values handed in (plan §4.7:918–919). */
+    readonly buildInputsHash: string;
+    readonly blocked?: {
+        readonly reason: AppBuildBlockedReason;
+        readonly detail: Record<string, string | number | string[]>;
+    };
+}
+/** What the sync is called with. */
+interface BuildValueSyncInput {
+    readonly values: readonly BuildValue[];
+    /** The `EW_` names the platform wrote earlier and may now delete (plan §4.7:916–917). */
+    readonly previouslyWrittenSecretNames: readonly string[];
+}
+/** The result of writing §4.10's per-verification prompted-value secret. */
+interface VerifyPromptedSecretResult {
+    readonly name: string;
+    /** The JSON payload's size in bytes — the same 48,000-byte ceiling every other value has. */
+    readonly bytes: number;
+    readonly blocked?: {
+        readonly reason: AppBuildBlockedReason;
+        readonly detail: Record<string, string | number | string[]>;
+    };
+}
+/** The factory's dependencies. */
+interface SecretSyncDependencies {
+    readonly port: RepositorySecretPort;
+    readonly logger?: SecretSyncLogger;
+    /** Test seam for the seal. Defaults to {@link sealSecretValue} — the real libsodium sealed box. */
+    readonly seal?: (value: string, publicKey: string) => Promise<string>;
+}
+/** The operations §4.7 and §4.10 need, bound to one repository port. */
+interface BuildValueSecretSync {
+    syncBuildValues(input: BuildValueSyncInput): Promise<BuildValueSyncResult>;
+    /** §4.10: the prompted values the owner set, as **one** JSON secret, just before dispatch. */
+    writeVerifyPromptedSecret(values: readonly BuildValue[]): Promise<VerifyPromptedSecretResult>;
+    /** §4.10: delete that secret by name, on the Build's terminal transition and in the sweep. */
+    deleteVerifyPromptedSecret(): Promise<{
+        readonly deleted: boolean;
+    }>;
+}
+/** GitHub's own secret-name rule, as the github plugin applies it (plan §4.7:914). */
+declare const GITHUB_SECRET_NAME_PATTERN: RegExp;
+/** True when GitHub would accept this secret name. */
+declare function isValidGitHubSecretName(name: string): boolean;
+/** The `EW_` name a build value is stored under. */
+declare function buildSecretName(valueName: string): string;
+declare function loadSodium(): Promise<typeof sodiumType>;
+/**
+ * Seal one value with a repository public key — the sequence of
+ * `github-actions.service.ts:64-73`, unchanged.
+ */
+declare function sealSecretValue(value: string, publicKey: string): Promise<string>;
+/** GitHub's repository-secret limit answer, recognised without pinning a message GitHub may reword. */
+declare function isSecretLimitError(error: unknown): boolean;
+/**
+ * Build the §4.7/§4.10 operations over one repository port.
+ *
+ * Every operation fetches the public key once, at its own start: a key can rotate
+ * between a preparation and a verification, and a cached key would seal a value
+ * GitHub then refuses to decrypt.
+ */
+declare function createBuildValueSecretSync(dependencies: SecretSyncDependencies): BuildValueSecretSync;
+
+/**
+ * APW-05 T7 — the `github-actions-build` plugin settings (plan §4.4, setting by
+ * setting), and the one place the two platform-managed keys are declared.
+ *
+ * Every key, default, bound and marker below is transcribed from plan §4.4's
+ * table. Nothing is invented: no key appears that the table does not state, so a
+ * tightening of this schema cannot silently refuse a configuration the plan
+ * allows.
+ *
+ * ## What is load-bearing here, and why (pinned by
+ * `src/__tests__/plugin.manifest.spec.ts` rather than asserted in prose)
+ *
+ *   - **`pullToken` is `x-secret`** (Constitution VII, plan §4.12). The marker is
+ *     the only thing that makes the platform treat the value as a secret:
+ *     `packages/plugin/src/api/api-response.types.ts` turns it into
+ *     `secret: true` on the descriptor every API response is built from, and
+ *     `plugin-operations.service.ts` masks exactly those fields. Drop the marker
+ *     and the pull token becomes an ordinary setting, readable back out of the
+ *     settings API.
+ *   - **`pullToken` and `pullTokenExpiresAt` are `x-platformManaged`** (plan
+ *     §4.4, `APW05-G07`): only `AppBuildPullTokenService.save` (APW-05 T29)
+ *     writes them, through `PluginSettingsService.writePlatformManagedWorkSettings`,
+ *     and the generic settings PATCH route must refuse both at every scope.
+ *   - **no preparation key is declared** (`APW05-G03`). `workflowSha256`,
+ *     `workflowPullRequestNumber`, `webhookId`, `runsEtag` and `repositoryBlock`
+ *     are *preparation* state: their one home is the per-App-Work
+ *     `work_build_preparations` row (plan §3.1b, landed in APW-05 T4/T5/T6), so
+ *     a user cannot PATCH what only the platform may write. Declaring one here
+ *     would put it back in reach of the settings API.
+ *
+ * ## `x-platformManaged` and the shared schema type
+ *
+ * `PluginSchemaExtensions` (`packages/plugin/src/settings/json-schema.types.ts`)
+ * does not declare `x-platformManaged`, and `PluginSettingsService.validateSettingsScope`
+ * (`packages/agent/src/plugins/services/plugin-settings.service.ts:812`) does not
+ * read it yet. Both files belong to other epics' slices, so the marker is
+ * declared **locally** by {@link PlatformManagedJsonSchema} — the narrowest
+ * annotation that lets plan §4.4's two markers exist in the schema today without
+ * a cast that would hide them. When the shared type grows the flag, this
+ * interface collapses to `JsonSchema` and nothing else moves. Until the service
+ * reads it, the marker is declared and asserted here while the refusal it
+ * enables is T29's (`APW05-G07`).
+ */
+/**
+ * `JsonSchema` plus plan §4.4's platform-managed marker.
+ *
+ * A local widening, deliberately: the shared extension interface is owned by
+ * another slice (see the file docstring).
+ */
+interface PlatformManagedJsonSchema extends JsonSchema {
+    /** Written by the platform only; the settings PATCH route refuses it at every scope (plan §4.4, `APW05-G07`). */
+    readonly 'x-platformManaged'?: boolean;
+}
+/** This plugin's settings schema — a {@link JsonSchema} whose properties may carry {@link PlatformManagedJsonSchema}. */
+interface GitHubActionsBuildSettingsSchema extends JsonSchema {
+    readonly properties?: Record<string, JsonSchema | PlatformManagedJsonSchema>;
+}
+/** `largerRunnerLabel` (plan §4.4): private repositories only, when set. */
+declare const LARGER_RUNNER_LABEL_PATTERN = "^[A-Za-z0-9._-]{1,64}$";
+/** Memory the platform reserves before a declared `memoryGiB` is allowed to fit (plan §4.4: `memory − 2`). */
+declare const LARGER_RUNNER_MEMORY_MIN_GIB = 8;
+/** Upper bound of `largerRunnerMemoryGiB` (plan §4.4). */
+declare const LARGER_RUNNER_MEMORY_MAX_GIB = 256;
+/** Lower bound of `largerRunnerVcpu` (plan §4.4). */
+declare const LARGER_RUNNER_VCPU_MIN = 2;
+/** Upper bound of `largerRunnerVcpu` (plan §4.4). */
+declare const LARGER_RUNNER_VCPU_MAX = 64;
+/**
+ * Every settings key this plugin declares, in plan §4.4's table order.
+ *
+ * Exported so the spec can assert the set, the order and the markers against one
+ * list instead of three hand-copied ones.
+ */
+declare const GITHUB_ACTIONS_BUILD_SETTING_KEYS: readonly ["largerRunnerLabel", "largerRunnerMemoryGiB", "largerRunnerVcpu", "reclaimDisk", "attestations", "pullToken", "pullTokenExpiresAt", "allowBuildValuesOnPullRequests", "verificationPromptedValuesRequireApproval"];
+/** A settings key of this plugin (plan §4.4). */
+type GitHubActionsBuildSettingKey = (typeof GITHUB_ACTIONS_BUILD_SETTING_KEYS)[number];
+/** The keys the platform writes and a user may never set (plan §4.4, `APW05-G07`). */
+declare const GITHUB_ACTIONS_BUILD_PLATFORM_MANAGED_KEYS: readonly ["pullToken", "pullTokenExpiresAt"];
+/**
+ * The preparation keys of plan §3.1b that this schema must NOT declare
+ * (`APW05-G03`). Named here so the negative assertion has one authority, and so
+ * the collision with the `work_build_preparations` columns is visible from the
+ * plugin side too.
+ */
+declare const PREPARATION_STATE_KEYS: readonly ["workflowSha256", "workflowPullRequestNumber", "webhookId", "runsEtag", "repositoryBlock"];
+/** The defaults plan §4.4 gives the four booleans and the two runner numbers. */
+declare const GITHUB_ACTIONS_BUILD_SETTING_DEFAULTS: {
+    readonly largerRunnerLabel: "";
+    readonly largerRunnerMemoryGiB: 0;
+    readonly largerRunnerVcpu: 0;
+    readonly reclaimDisk: true;
+    readonly attestations: false;
+    readonly allowBuildValuesOnPullRequests: false;
+    readonly verificationPromptedValuesRequireApproval: true;
+};
+/**
+ * The settings this plugin reads once resolved (plan §4.4).
+ *
+ * `pullToken`/`pullTokenExpiresAt` are optional: they exist only after
+ * `AppBuildPullTokenService` has written them (plan §4.12).
+ */
+interface GitHubActionsBuildSettings {
+    largerRunnerLabel?: string;
+    largerRunnerMemoryGiB?: number;
+    largerRunnerVcpu?: number;
+    reclaimDisk?: boolean;
+    attestations?: boolean;
+    pullToken?: string;
+    pullTokenExpiresAt?: string;
+    allowBuildValuesOnPullRequests?: boolean;
+    verificationPromptedValuesRequireApproval?: boolean;
+}
+/**
+ * Plan §4.4's table as a JSON Schema.
+ *
+ * Scope, resolved from the table's own statements rather than from its summary
+ * sentence, which pulls in two directions: the notes mark **Work scope only**
+ * for `allowBuildValuesOnPullRequests` and `verificationPromptedValuesRequireApproval`
+ * explicitly, and plan §4.4:799 says "Work scope only for `pullToken`,
+ * `largerRunner*`, `attestations`; user and admin scope may set defaults for
+ * `reclaimDisk` and `largerRunner*`". Both cannot hold for `largerRunner*`, so
+ * the schema follows the second half (a user/admin **default** that a Work
+ * overrides) and keeps `pullToken`, `pullTokenExpiresAt`, `attestations` and the
+ * two XC-01 booleans at `x-scope: 'work'`, which is what the platform's scope
+ * model can express. Recorded for T11, which owns the runner selector and reads
+ * these three keys.
+ */
+declare const gitHubActionsBuildSettingsSchema: GitHubActionsBuildSettingsSchema;
+
+/**
+ * APW-05 T7 — the `github-actions-build` plugin: the identity the platform's
+ * discovery path and the `build` capability need, the settings of plan §4.4, and
+ * the members T8–T10 have not reached yet.
+ *
+ * What exists here:
+ *
+ *   - the manifest the `everworks.plugin` block in `package.json` also declares
+ *     (they must agree — `plugin-manifest-validator.service.ts` extracts the
+ *     block from disk and `plugin-class-validator.service.ts` compares the loaded
+ *     class against it);
+ *   - `settingsSchema` — plan §4.4, with `pullToken` `x-secret` and both
+ *     platform-managed markers (`APW05-G07`);
+ *   - the two lifecycle hooks the loader calls. Both are **prototype methods on
+ *     purpose**: `PluginClassValidatorService.isPluginClass` accepts a class only
+ *     when `onLoad` and `onUnload` sit on its prototype, so an arrow-function
+ *     property would make this plugin undiscoverable.
+ *
+ * ## Every `IBuildPlugin` member is implemented (Constitution VI, Rule: a
+ * ## capability a plugin claims, it implements — no member pretends)
+ *
+ * **All five, as of 2026-09-22.** T12 did four on 2026-09-21; T11's runner
+ * selector landed the next day, T41's checks job turned out to be already
+ * written, and §4.6 could then be composed — so `prepareRepository` is the last
+ * one and the `notImplemented` list is empty.
+ *
+ * | Member                | Detail                                                                                                    |
+ * | --------------------- | ----------------------------------------------------------------------------------------------------------- |
+ * | `prepareRepository`   | §4.6: select the runner (T11), generate the file (T8) with the checks job (T41), deliver it (T9), then sync the build values (T10) — in that order, so nothing reaches a member's repository until it is known the Build could run |
+ * | `startBuild`          | dispatches the generated file on the TRACKED branch with `ew_build_id` / `ew_sha` / `ew_mode` and the two optional inputs, then correlates once |
+ * | `getBuild`            | run + jobs → `BuildSnapshot` via `runs/run-observer.ts`, plus the result artifact for a finished run and, for a FAILED one, the log tail (T13) classified into `failure`. T43 fills `verification` |
+ * | `cancelBuild`         | resolves the same run `getBuild` would, then the cancel endpoint                                          |
+ * | `getLogsUrl`          | the run's own page                                                                                        |
+ *
+ * What is deliberately still NOT done, so nobody reads the table above as more
+ * than it says:
+ *
+ *   - the **404/422 retry after a bootstrap commit** (`APW05-G02`) — a
+ *     just-written workflow file is briefly undispatchable;
+ *   - a digest read from the artifact is reported `confirmed: false` **always**.
+ *     Confirming it is `checkImageAccess` (T14, below) and the comparison belongs
+ *     to the caller, `AppBuildsService.finalize` (plan §4.8). For a succeeded
+ *     push or manual run the snapshot also carries `image.pushLogDigest`, the
+ *     digest the build job's Push step logged (`runs/push-digest.ts`), which the
+ *     caller weighs only when the registry cannot be read;
+ *   - a failure whose log has EXPIRED classifies as `unknown`. GitHub deletes
+ *     job logs on the repository's retention schedule, and a Build observed
+ *     after that is genuinely unexplainable — reporting `unknown` is the honest
+ *     answer, and re-running the Build is the only way to get a better one.
+ *
+ * `checkImageAccess?` (T14) IS declared now, because it does something: it reads
+ * the manifest through GHCR's token exchange (`ghcr.io/token`, then a `HEAD` with
+ * the registry-issued bearer) — anonymously, then with the pull token presented
+ * to `/token` as Basic credentials — and checks that token's scopes through
+ * `GET /user`. It is the confirming half of §4.8's "only ever confirmed, never
+ * believed" — `getBuild` still reports an artifact digest as `confirmed: false`
+ * always, and `AppBuildsService.finalize` does the comparison, because it is the
+ * only party holding both the Build row and the `pullToken` setting.
+ *
+ * `listRecentRuns?` (T12's run discovery, §7.4a) is still deliberately **not
+ * declared**: it is optional on the contract and a caller materialises the member
+ * before calling it, so declaring a throwing placeholder would buy nothing and
+ * would tell a future reader the capability is wired when it is not.
+ */
+declare class GitHubActionsBuildPlugin implements IBuildPlugin {
+    readonly id = "github-actions-build";
+    readonly name = "GitHub Actions builds";
+    readonly version = "1.0.0";
+    /**
+     * Plan §4.3: the `build` category — appended to `PLUGIN_CATEGORIES` by APW-05
+     * T3 (`packages/plugin/src/contracts/plugin-manifest.types.ts`), so the
+     * loader's own `isPluginCategory` gate accepts this manifest.
+     */
+    readonly category: PluginCategory;
+    /** Plan §4.3: exactly one capability. `isBuildPlugin` resolves this plugin on it. */
+    readonly capabilities: readonly string[];
+    /** Plan §4.3. `AppBuildKind` — a closed union in `@ever-works/contracts`. */
+    readonly buildKind: AppBuildKind;
+    /**
+     * Plan §4.1/R-13: `dockerfile` only.
+     *
+     * `auto` is deliberately absent: the zero-config builder is a provider-internal
+     * choice this plugin does not have, so the strategy gate leaves that Build
+     * unstarted (`strategyNotSupported`) rather than half-built. `image` and `none`
+     * are absent for the same reason — they need no build at all, and the prepare
+     * runner handles them before a build plugin is asked (plan §7.2).
+     */
+    readonly supportedStrategies: readonly BuildStrategy[];
+    /** Work-scoped settings, like the other per-Work provider plugins. */
+    readonly configurationMode = "user-required";
+    /** Plan §4.4, exactly. */
+    readonly settingsSchema: JsonSchema;
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): Promise<void>;
+    /**
+     * The Actions API this plugin talks to, bound per call from the caller's auth.
+     *
+     * `protected` and a method, not a constructor seam: the loader constructs a
+     * plugin with **no arguments** (`PluginLoaderService.loadPluginModule` —
+     * `new PluginClass()`), so anything a spec wants to replace has to be
+     * replaceable on the instance. A spec subclasses and overrides this; production
+     * gets Octokit, which is the official SDK and already this package's dependency.
+     *
+     * A fresh client per call, deliberately: `auth.token` is resolved per call by
+     * the facade (plan §4.1) and may be a different member's installation token
+     * from one call to the next. Caching one would be caching a credential.
+     */
+    protected actionsPort(auth: BuildAuth): ActionsRunsPort;
+    /** The clock, as a seam, so the correlation window is provable without waiting. */
+    protected now(): number;
+    getManifest(): PluginManifest;
+    /**
+     * APW-05 §4.6 — put the workflow (and the build values) where a Build can use them.
+     *
+     * Four steps, in this order, and the order is the point: nothing is written to a
+     * member's repository until it is known the Build could run at all.
+     *
+     *  1. **Select the runner** (T11). A declared memory the chosen runner cannot
+     *     give is `runnerTooSmall`, and it BLOCKS here — before a commit, before a
+     *     secret, before anything reaches GitHub. The alternative is writing a
+     *     workflow that is guaranteed to be OOM-killed minutes into its first run.
+     *  2. **Generate the file** (T8), with the checks job (T41) when the spec
+     *     declares checks and the verify job when the App Work can verify.
+     *  3. **Deliver it** (T9): unchanged, committed, or a pull request for a
+     *     repository that is not ours to write into (R-4). A hand-edited file is
+     *     `editedByHand` and is never overwritten.
+     *  4. **Sync the build values** (T10), and only then — a secret written for a
+     *     workflow that was never delivered is a secret nobody will clean up.
+     *
+     * ## The two failure shapes, kept apart
+     *
+     * A `blocked` result is a Build that will not start and a member who is told
+     * why. A THROW is this plugin failing at its own job. `writeWorkflow`'s own
+     * `'blocked'` state is mapped onto `PrepareRepositoryResult.blocked` rather than
+     * passed through, because that state is the writer's and is not one of the five
+     * the contract's `workflow.state` allows — the writer's docstring says so, and
+     * storing it would put a value in the database that no reader understands.
+     *
+     * ## `contentSha256` is stored only after a matching read-back
+     *
+     * `storedWorkflowSha256` is `null` until the writer has PROVEN the tracked
+     * branch holds the generated bytes (FR-8). Reporting the hash of what we sent,
+     * rather than of what is there, is how a failed write becomes an unnoticed
+     * hand-edit detection failure on the next preparation.
+     */
+    prepareRepository(input: PrepareRepositoryInput, auth: BuildAuth, writer: RepositoryWriter): Promise<PrepareRepositoryResult>;
+    /**
+     * The repository-secret operations T10's sync needs, over Octokit.
+     *
+     * A seam for the same reason {@link actionsPort} is one: the loader constructs
+     * this class with no arguments, so a spec replaces it on the instance.
+     */
+    protected secretPort(auth: BuildAuth, repository: {
+        readonly owner: string;
+        readonly repo: string;
+    }): RepositorySecretPort;
+    /**
+     * APW-05 T12 — dispatch the generated workflow on the App Work's tracked branch.
+     *
+     * ## `providerRunId` is `null` here, and that is not a failure
+     *
+     * `POST .../dispatches` answers **204 with no body**: GitHub says nothing about
+     * the run it just created. So this method dispatches, records the instant, and
+     * makes ONE correlation attempt; the run is usually not listed that fast, and a
+     * `null` id is the normal answer. `app-build-watch` polls `getBuild`, which
+     * correlates again on every poll. Blocking here until a run appeared would hold
+     * the caller's request open for an arbitrary provider delay.
+     *
+     * ## The branch is the tracked branch, never the caller's ref
+     *
+     * FR-14: a Build may only run for the App Work's tracked branch. `input.ref` is
+     * what to BUILD; `repository.trackedBranch` is where the workflow file lives and
+     * the only `ref` a dispatch is allowed to name. Passing `input.ref` would let a
+     * Build run a workflow file from a branch nobody reviewed.
+     */
+    startBuild(input: StartBuildInput, auth: BuildAuth): Promise<{
+        providerRunId: string | null;
+        dispatchedAt: string;
+    }>;
+    /**
+     * APW-05 T12 — observe one run.
+     *
+     * Correlates first when the ref carries no `providerRunId`: a Build dispatched
+     * moments ago has none, and the watch job's whole purpose is to find it. `null`
+     * means "no such run" — never "I could not tell", which the contract says is a
+     * throw, and which is why a failed API call is not caught here.
+     *
+     * `redact` is APW-07's redactor for this App Work, and it is USED: every line
+     * of every excerpt goes through it, and through the secret-shape mask after
+     * it, before it leaves this method (FR-38).
+     */
+    getBuild(ref: BuildRef, auth: BuildAuth, redact: (text: string) => string): Promise<BuildSnapshot | null>;
+    /**
+     * APW-05 T13 — why a failed run failed, as `BuildSnapshot.failure`.
+     *
+     * ## Which job's log
+     *
+     * The `build` job decides the Build's status (`run-observer.ts`, R-9), so when
+     * it failed it is the one worth reading. Only when it did NOT fail — a Build
+     * the run marked failed for some other reason — does any other failing job
+     * stand in. A failed `Ever Works check:` job is deliberately last: it never
+     * flips a Build to `failed`, so if it is the only failure the run's own
+     * conclusion is what actually needs explaining.
+     *
+     * No failing job at all is not an error: `jobCount` then carries the run into
+     * the classifier's `workflowInvalid` row, which is exactly what a run that
+     * produced no jobs is.
+     *
+     * ## Why the artifact's smoke rows are passed in
+     *
+     * `verificationFailed` is a class the LOG cannot show: the smoke rows live in
+     * the result artifact, which `getBuild` has already read by this point. Passing
+     * them costs nothing and is the difference between "your build failed" and
+     * "your app built, and then did not answer".
+     */
+    private classifyRunFailure;
+    /**
+     * APW-05 T14 remainder — the digest the build job's `Push` step logged for
+     * this Build's `sha-<sha>` tag, or `undefined`.
+     *
+     * The BUILD job's log, because that is the job holding the Push step; read as
+     * the same bounded tail T13 reads (the Push step is near the end of the job,
+     * followed only by the result write and the upload). An unreadable or expired
+     * log is `''` from `readJobLogTail`, so this never fails an observation — it
+     * only costs the fallback. Which lines count is `runs/push-digest.ts`'s rule.
+     */
+    private readPushLogDigest;
+    /**
+     * The run this ref addresses: the one it names, or the one correlation finds.
+     *
+     * Shared by `getBuild`, `cancelBuild` and `getLogsUrl` so all three agree about
+     * which run a ref means — a cancel that addressed a different run from the
+     * observation would stop the wrong Build.
+     */
+    private resolveRunId;
+    /**
+     * APW-05 T12 — stop the run.
+     *
+     * A ref that resolves to no run is a no-op rather than a throw: the caller asked
+     * for the Build to stop, and a Build with no run has stopped. The port swallows
+     * GitHub's 409 ("not cancellable") for the same reason — a finished run is not a
+     * failed cancel.
+     */
+    cancelBuild(ref: BuildRef, auth: BuildAuth): Promise<void>;
+    /**
+     * APW-05 T14 — can this installation read the image, and is its pull token the
+     * right shape?
+     *
+     * Declared now that it does something. It stayed undeclared while it did not,
+     * because the contract makes it optional and a caller materialises the member
+     * before calling it — so a throwing placeholder would have told a reader the
+     * capability was wired when it was not.
+     *
+     * This is the **confirming** half of plan §4.8's "only ever confirmed, never
+     * believed". `getBuild` reports the digest the member's own CI claimed with
+     * `confirmed: false`, always; comparing it against the digest this method reads
+     * from the registry is what makes it true, and that comparison belongs to the
+     * caller — `AppBuildsService.finalize` — which is the only party holding both
+     * the Build row and the installation's `pullToken` setting (`getBuild(ref, auth)`
+     * is given neither).
+     *
+     * The registry is read through GHCR's own token exchange (`registry/ghcr-access.ts`):
+     * a bare manifest `HEAD` is 401 for every image on GHCR, public or not, so a
+     * public image is only ever seen as public through the anonymous registry token.
+     * The pull token reaches `ghcr.io/token` (as Basic) and `api.github.com/user`,
+     * and nothing else.
+     */
+    checkImageAccess(input: {
+        readonly imageRepository: string;
+        readonly tag: string;
+        readonly pullToken?: string;
+    }): Promise<GhcrAccessResult>;
+    /**
+     * The registry/API HTTP seam.
+     *
+     * `redirect: 'manual'` is set by `ghcr-access.ts` on every request and passed
+     * straight through here: a 3xx followed with the `Authorization` header still
+     * attached is how a pull token reaches a host that is neither `api.github.com`
+     * nor `ghcr.io`, and that module's spec watches every call for exactly that.
+     */
+    protected registryFetch(): GhcrFetch;
+    /** APW-05 T12 — the run's own page, which is where a member reads its logs. */
+    getLogsUrl(ref: BuildRef, auth: BuildAuth): Promise<string | null>;
+}
+/**
+ * The error every unimplemented member throws.
+ *
+ * One shape and one message format, so a caller can tell "this plugin does not
+ * do that yet" from a provider failure — and so the message names the task that
+ * will make it true rather than a bare "not implemented".
+ */
+declare function notImplemented(member: string, owner: string): Error;
+
+/**
+ * APW-05 T8 — the third-party actions the generated workflow is allowed to use,
+ * pinned to a commit.
+ *
+ * Plan §4.5: "`ACTION_PINS` values are 40-character commit hashes with the
+ * release tag in a trailing comment; a unit test fails when any pin is not 40 hex
+ * characters. Bumping pins bumps `inputsHash`, so every App Work gets a pull
+ * request or commit with the new file on its next preparation."
+ *
+ * ## How these five were resolved (and how to bump them)
+ *
+ * Each `sha` is the **commit** a release tag pointed at when this file was
+ * written, read with `git ls-remote --tags https://github.com/<owner>/<repo>`,
+ * peeling annotated tags (`^{}`) so a tag object's hash can never be mistaken for
+ * a commit. `resolvedOn` records the day. A bump is: re-run that command, take
+ * the newest stable tag's commit, update `sha` + `tag` + `resolvedOn` — nothing
+ * else changes, and `inputsHash` moves on its own.
+ *
+ * The five names are exactly the plan §4.3 generator's set. A sixth action is
+ * not "just another entry": §4.5's pin set is what the golden files pin, so a new
+ * action is a new decision about what runs inside a customer's repository.
+ */
+interface ActionPin {
+    /** `owner/repo`, as it appears before the `@` in a `uses:` line. */
+    readonly action: string;
+    /** The release tag this commit was the tip of, for the trailing comment. */
+    readonly tag: string;
+    /** The 40-character commit hash that must appear after the `@`. */
+    readonly sha: string;
+    /** The day `sha` was resolved from the tag. */
+    readonly resolvedOn: string;
+}
+declare const ACTION_PINS: {
+    /** `actions/checkout@v7.0.1`. */
+    readonly checkout: {
+        readonly action: "actions/checkout";
+        readonly tag: "v7.0.1";
+        readonly sha: "3d3c42e5aac5ba805825da76410c181273ba90b1";
+        readonly resolvedOn: "2026-09-18";
+    };
+    /** `docker/setup-buildx-action@v4.4.1`. */
+    readonly setupBuildx: {
+        readonly action: "docker/setup-buildx-action";
+        readonly tag: "v4.4.1";
+        readonly sha: "f87e5991a6d7451dcb8d9637bfbc97413f497069";
+        readonly resolvedOn: "2026-09-18";
+    };
+    /** `docker/login-action@v4.6.0`. */
+    readonly login: {
+        readonly action: "docker/login-action";
+        readonly tag: "v4.6.0";
+        readonly sha: "dbcb813823bdd20940b903addbd779551569679f";
+        readonly resolvedOn: "2026-09-18";
+    };
+    /** `docker/build-push-action@v7.4.0`. */
+    readonly buildPush: {
+        readonly action: "docker/build-push-action";
+        readonly tag: "v7.4.0";
+        readonly sha: "c3c9e263c25d99ce0380d002d59b67737d91b0dc";
+        readonly resolvedOn: "2026-09-18";
+    };
+    /** `actions/upload-artifact@v7.0.1`. */
+    readonly uploadArtifact: {
+        readonly action: "actions/upload-artifact";
+        readonly tag: "v7.0.1";
+        readonly sha: "043fb46d1a93c77aae656e7c1c64a875d1fc6a0a";
+        readonly resolvedOn: "2026-09-18";
+    };
+};
+/** The keys of {@link ACTION_PINS}, in declaration order. */
+type ActionPinKey = keyof typeof ACTION_PINS;
+/** A commit hash, and nothing else — plan §4.5's "40 hex characters" (ACC-05-05). */
+declare const ACTION_PIN_SHA_PATTERN: RegExp;
+/** `owner/repo@<40 hex>  # <tag>` — the exact `uses:` value, comment included. */
+declare function actionPin(pin: ActionPin): string;
+/** `owner/repo@<40 hex>` — the pin without its trailing comment, for a canonical input. */
+declare function actionPinReference(pin: ActionPin): string;
+/**
+ * The pin set in canonical form: key → `owner/repo@<40 hex>`, keys sorted.
+ *
+ * This is what `inputs-hash.ts` hashes, so a bump moves `inputsHash` (and
+ * `resolvedOn` deliberately does **not**: it records when the hash was read, not
+ * what will run).
+ */
+declare function canonicalActionPins(): Record<string, string>;
+/**
+ * Names the generated workflow must never reference in clear text.
+ *
+ * Exported for the generator's own guard rather than for a caller: the
+ * restricted pull-request literal and the check-name prefix are the two strings
+ * the golden and generator specs assert against each other.
+ */
+declare const GENERATOR_RESERVED_LITERALS: readonly ["ew-restricted", "Ever Works check: "];
+
+/**
+ * APW-05 T8 — the canonical inputs of a generated workflow and their fingerprint.
+ *
+ * Plan §4.5: "**Canonical inputs**: `{ generator: 1, trackedBranch, build
+ * (normalised: defaults applied, keys sorted), values: names + secret +
+ * fromBuildService (never values), runner: { label, class }, settings: {
+ * reclaimDisk, attestations }, pins: ACTION_PINS, verifyEnabled, checks: [{ name,
+ * required, timeoutMinutes, commandSha256 }] }`. `inputsHash = sha256(canonical
+ * JSON)`."
+ *
+ * ## Why this canonical set is wider than the plan's line, deliberately
+ *
+ * The line above was written before `XC-01` (2026-09-17) added
+ * `allowBuildValuesOnPullRequests`, and it never mentioned the repository, the
+ * App spec hash, the bootstrap flag or the embedded verify-runner script — all of
+ * which change the generated **bytes**. A fingerprint that stays still while the
+ * bytes move is worse than no fingerprint: plan §4.5 relies on it to decide
+ * whether an App Work needs a new commit or pull request ("Bumping pins bumps
+ * `inputsHash`, so every App Work gets a pull request or commit with the new file
+ * on its next preparation"), and §2.4's header line publishes it as the file's
+ * identity. So every field below is either the plan's own or one that changes the
+ * output, and {@link CANONICAL_INPUT_FIELDS} lists them in one place.
+ *
+ * `values` keeps the plan's rule exactly: **names, `secret` and
+ * `fromBuildService` only — never a value, never a fingerprint.** Two App Works
+ * whose `DATABASE_URL` is the same env entry name with different stored values
+ * have the same workflow bytes, and that is the point: rotating a secret must not
+ * rewrite a workflow file.
+ *
+ * The JSON form is fixed here rather than left to `JSON.stringify`'s insertion
+ * order: keys are written in {@link CANONICAL_INPUT_FIELDS} order, arrays that
+ * the caller may hand in unordered (values, build args, services, checks) are
+ * sorted by their own key, and the result contains no whitespace — so the same
+ * inputs hash the same on every platform (ACC-05-03).
+ */
+/** One build service, canonicalised (plan §2.4 `services`, §4.5 `BUILD_SERVICE_DEFAULTS`). */
+interface CanonicalBuildService {
+    readonly name: string;
+    readonly image: string;
+    /** The declared published port, when the App spec gives one. */
+    readonly port?: number;
+    /** The declared `env`, sorted by name — the image defaults are applied at emission, not here. */
+    readonly env: ReadonlyArray<{
+        readonly name: string;
+        readonly value: string;
+    }>;
+}
+/** One build argument, canonicalised (plan §2.4 `build-args`). */
+interface CanonicalBuildArg {
+    readonly name: string;
+    /** A literal value, as written in the App spec. */
+    readonly value?: string;
+    /** The build-value name this argument reads from the repository secrets. */
+    readonly fromEnv?: string;
+}
+/** The App spec's `build` block, normalised (plan §4.5: "defaults applied, keys sorted"). */
+interface CanonicalBuildBlock {
+    readonly strategy: string;
+    /** `build.context`, defaulted to `.` — plan §2.4 `context: <build.context>`. */
+    readonly context: string;
+    /** `build.dockerfile`, defaulted to `Dockerfile`, relative to the repository root. */
+    readonly dockerfile: string;
+    readonly target?: string;
+    readonly args: readonly CanonicalBuildArg[];
+    readonly services: readonly CanonicalBuildService[];
+    readonly resources: {
+        readonly cpu: number;
+        readonly memoryGiB?: number;
+        readonly timeoutMinutes: number;
+    };
+}
+/** One synced build value's contribution — plan §4.5: "names + secret + fromBuildService (never values)". */
+interface CanonicalBuildValue {
+    readonly name: string;
+    readonly secret: boolean;
+    readonly fromBuildService: boolean;
+}
+/** One App spec check (R-9, plan §4.5) — the command travels as its digest. */
+interface CanonicalCheck {
+    readonly name: string;
+    readonly required: boolean;
+    /** `ceil(timeoutSeconds / 60)` — the plan's unit. */
+    readonly timeoutMinutes: number;
+    readonly commandSha256: string;
+}
+/** The runner the workflow will ask for (plan §4.5 `runner: { label, class }`). */
+interface CanonicalRunner {
+    readonly label: string;
+    readonly class: AppBuildRunnerClass;
+}
+/** The two settings that change the emitted bytes (plan §4.4, §4.5) plus XC-01's opt-out. */
+interface CanonicalSettings {
+    readonly reclaimDisk: boolean;
+    /** The **effective** value: `settings.attestations === true && repository.visibility === 'public'` (plan §4.5, `APW05-G07`). */
+    readonly attestations: boolean;
+    readonly allowBuildValuesOnPullRequests: boolean;
+    readonly verificationPromptedValuesRequireApproval: boolean;
+}
+/** Everything the fingerprint covers, in the order the canonical JSON writes it. */
+interface CanonicalWorkflowInputs {
+    readonly generator: typeof APP_BUILD_GENERATOR_VERSION;
+    readonly bootstrap: boolean;
+    readonly trackedBranch: string;
+    readonly repository: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly visibility: 'public' | 'private';
+    };
+    readonly appSpecHash: string;
+    /** `null` for the bootstrap file of plan §4.6 step 0, which carries no build block. */
+    readonly build: CanonicalBuildBlock | null;
+    readonly values: readonly CanonicalBuildValue[];
+    readonly runner: CanonicalRunner;
+    readonly settings: CanonicalSettings;
+    readonly pins: Record<string, string>;
+    readonly verifyEnabled: boolean;
+    readonly checks: readonly CanonicalCheck[];
+    /** sha256 of the embedded verify-runner script — a T15 change must move the file. */
+    readonly verifyRunnerScriptSha256: string;
+}
+/**
+ * The canonical key order, as data.
+ *
+ * `canonicalJson` writes exactly these keys in this order; the spec asserts that
+ * this list and the emitted header agree, so adding a field cannot half-land.
+ */
+declare const CANONICAL_INPUT_FIELDS: readonly ["generator", "bootstrap", "trackedBranch", "repository", "appSpecHash", "build", "values", "runner", "settings", "pins", "verifyEnabled", "checks", "verifyRunnerScriptSha256"];
+/** `ceil(timeoutSeconds / 60)` — the plan's minutes unit for a check (R-9, plan §4.5). */
+declare function checkTimeoutMinutes(timeoutSeconds: number): number;
+/** A check as the canonical inputs carry it — the command only as its digest. */
+declare function canonicalCheck(check: {
+    readonly name: string;
+    readonly command: string;
+    readonly required: boolean;
+    readonly timeoutSeconds: number;
+}): CanonicalCheck;
+/**
+ * Sort the parts a caller may hand in unordered, so the canonical JSON — and the
+ * hash — is order-independent (ACC-05-03).
+ *
+ * `values` by name (then `secret`, then `fromBuildService`, so two entries that
+ * somehow share a name still order deterministically); build args by name;
+ * services by name; checks by name.
+ */
+declare function canonicaliseWorkflowInputs(inputs: CanonicalWorkflowInputs): CanonicalWorkflowInputs;
+/** The canonical JSON of {@link CANONICAL_INPUT_FIELDS}, no whitespace, fixed key order. */
+declare function canonicalWorkflowJson(inputs: CanonicalWorkflowInputs): string;
+/** `sha256:<64 hex>` over {@link canonicalWorkflowJson} — the header line's fingerprint (plan §2.4, §4.5). */
+declare function computeWorkflowInputsHash(inputs: CanonicalWorkflowInputs): string;
+
+/**
+ * APW-05 T8 — canonical inputs in, the workflow file out (plan §2.4, §4.5).
+ *
+ * The file this produces is the platform's, not the user's: it is written to the
+ * tracked branch, hand edits are never overwritten (plan §4.6 step 5, T9), and
+ * every value it needs travels as a repository secret (`EW_<NAME>`, plan §4.7,
+ * T10) rather than as workflow text. Five properties are load-bearing and are
+ * pinned by `src/__tests__/generator.spec.ts` against the ten goldens under
+ * `src/__tests__/golden/`:
+ *
+ *   1. **Byte-stable.** Plan §4.5: a line-array builder plus {@link yamlString},
+ *      LF endings, one trailing newline, and every unordered input sorted before
+ *      it is hashed or emitted — the same inputs yield identical bytes on every
+ *      platform (ACC-05-03).
+ *   2. **No stored value ever appears.** A `fromEnv` argument is emitted as a
+ *      `secrets.EW_<NAME>` reference; the resolved value only ever exists inside
+ *      the job's environment and the sealed-box PUT (ACC-05-05). A literal
+ *      `value` argument *is* emitted verbatim — it is written in the App spec, not
+ *      resolved from a stored value, which is exactly the distinction plan §2.4's
+ *      two `build-args` lines draw.
+ *   3. **A pull request from another repository runs nothing.** The `build` job's
+ *      `if:` requires the head repository to be the repository, and the only job
+ *      that references `secrets.` is that one (ACC-05-06).
+ *   4. **`load: true`, `push: false`, then a separate `docker push`.** A secret
+ *      found in the image metadata is caught *before* a byte leaves the runner
+ *      (FR-21), which is why the secret check sits between the build and the push.
+ *   5. **The `verify` job can neither publish an image nor write the cache**
+ *      (FR-54): `packages: read`, no `docker push`, no `--push`, no `cache-to`,
+ *      and its own `verify-<buildId>` concurrency group so it can never replace —
+ *      or be replaced by — the push Build of the head commit (`APW05-G02`).
+ *
+ * ## The `checks` job
+ *
+ * T41 landed it: the job is `src/workflow/checks-job.ts`'s (R-9, plan §2.4:276–308,
+ * §4.14) and this file only decides **whether** it is emitted — after the `build`
+ * job, which is where §2.4's job order puts it (build → verify → checks), and only
+ * when the App spec declares at least one check and the file is not the bootstrap
+ * file of §4.6 step 0 (which has no App spec to read checks from). `checks` also
+ * travels into the canonical inputs, so the fingerprint covers a check-command
+ * change as well as the bytes (plan §4.5: "A check command change therefore
+ * changes the file and its fingerprint").
+ *
+ * ## The checks-only file (T42, R-9, FR-70)
+ *
+ * `image` and `none` never produce a Build (plan §7.2 step 2: "`strategy`
+ * `image`/`none` → no Build"), so a file generated for one of them must not carry
+ * a `build` job — and §4.14 fixes what it carries instead, exactly: "the header,
+ * `on: pull_request` only (no `push`, no `workflow_dispatch`), `permissions: {}`,
+ * the same concurrency block and the `checks` job — nothing else". That is
+ * {@link checksOnlyWorkflow}, reached through {@link checksOnlyFile}. With no
+ * check left there is no workflow content at all, and this function answers the
+ * empty string: §4.6 step 8's "with no checks, nothing is written", which
+ * `src/repo/workflow-writer.ts` turns into a removal proposed by pull request
+ * (FR-70, ACC-05-30).
+ *
+ * Two details of that file are deliberate and are why they are listed here:
+ *
+ *   - **No `run-name`.** §4.14's "nothing else" and the normative draft
+ *     `docs/specs/features/app-works/APW-05-builds/golden-draft/checks.ever-works-build.yml`
+ *     (which carries `run-name` in every other draft and none here) agree: nothing
+ *     correlates a checks-only run to a Build, because §4.14's observation records
+ *     none for this strategy.
+ *   - **Its concurrency group is the draft's, not the full file's** — the one
+ *     place where §4.14's prose ("the same concurrency block") and §4.14's own
+ *     draft disagree. The draft wins, on a measurement: the full file's group names
+ *     `inputs.ew_mode` and `inputs.ew_build_id`, and the `inputs` context exists
+ *     only for `workflow_dispatch`/`workflow_call`, so a checks-only file that
+ *     carried it would be a file GitHub may refuse. `actionlint` v1.7.12 agrees —
+ *     on the shared block it exits 1 with
+ *     `checks-only.yml:11:15: property "ew_mode" is not defined in object type {}`
+ *     (and `:11:66` for `ew_build_id`); on the draft's group it exits 0. Both
+ *     blocks come from ONE helper, {@link concurrencyLines}, so they cannot drift;
+ *     `generator.spec.ts` pins each shape from both sides. Routed as a finding
+ *     against §4.14's sentence, which is the artefact that should be corrected.
+ *
+ * ## What this generator deliberately does not emit
+ *
+ *   - **An attestation step.** Plan §4.5 says a private repository never gets "the
+ *     attestation permissions or steps", but §4.3's pin set carries no attestation
+ *     action and §2.4's step list no attestation step, so only the two permissions
+ *     are emitted. Routed, not invented.
+ *
+ * ## Three readings this file had to fix
+ *
+ *   - **The branch tag.** §2.4 writes `format('branch-{0}', '<branch slug>')`; the
+ *     slug is known at generation time, so it is emitted as the literal
+ *     `'branch-<slug>'` inside the same expression. Same value, one less
+ *     indirection, and the golden contains the tag verbatim.
+ *   - **The restricted literal** (XC-01). §4.7b:948–952 says "a fixed non-secret
+ *     marker, one per value name so a build script can still distinguish 'absent'
+ *     from 'present'". The marker is used **verbatim**
+ *     (`APP_BUILD_RESTRICTED_VALUE_LITERAL`) rather than suffixed with the name:
+ *     the constant is the platform's single definition of the marker, and a
+ *     name-carrying variant could be mistaken for a value.
+ *   - **The build job's "Verify in the runner" step.** §2.4 emits it guarded by
+ *     `inputs.ew_verify_plan != ''`, and `ew_verify_plan` is only ever non-empty
+ *     for a `verify`-mode dispatch — which the `build` job excludes. It is emitted
+ *     as §2.4 writes it and reported as unreachable rather than quietly dropped.
+ */
+/** The App Work's repository as the workflow needs it — the emit-time half of plan §4.5's canonical inputs. */
+interface WorkflowRepositoryInput {
+    readonly owner: string;
+    readonly repo: string;
+    readonly visibility: 'public' | 'private';
+}
+/** The runner the workflow asks for — T11 selects it, this file only prints it (plan §4.5). */
+interface WorkflowRunnerInput {
+    readonly label: string;
+    readonly class: AppBuildRunnerClass;
+}
+/** The plan §4.4 settings that change the emitted bytes. */
+interface WorkflowSettingsInput {
+    readonly reclaimDisk?: boolean;
+    /** Honoured only for a public repository — the effective value is resolved here (plan §4.5, `APW05-G07`). */
+    readonly attestations?: boolean;
+    readonly allowBuildValuesOnPullRequests?: boolean;
+    readonly verificationPromptedValuesRequireApproval?: boolean;
+}
+/** One App spec check, as `PrepareRepositoryInput.checks` carries it (R-9, plan §4.1). */
+interface WorkflowCheckInput {
+    readonly name: string;
+    readonly command: string;
+    readonly required: boolean;
+    readonly timeoutSeconds: number;
+}
+/** Everything the generator needs (plan §4.5's canonical inputs, plus the emit-time facts). */
+interface WorkflowGeneratorInput {
+    readonly trackedBranch: string;
+    readonly repository: WorkflowRepositoryInput;
+    /** The hash of the App spec this file was generated from — the `io.ever-works.app-spec-hash` label (plan §2.4). */
+    readonly appSpecHash: string;
+    /** The App spec's `build` block; `null` (or absent) for the bootstrap file of plan §4.6 step 0. */
+    readonly build?: AppBuildBlock | null;
+    readonly values: readonly BuildValue[];
+    readonly runner: WorkflowRunnerInput;
+    readonly settings?: WorkflowSettingsInput;
+    /** Plan §4.5: true exactly when the file carries the `verify` job that can run for this App Work. */
+    readonly verifyEnabled: boolean;
+    readonly checks?: readonly WorkflowCheckInput[];
+    /** Plan §4.6 step 0: a dispatch-only file with no `build` job and no `checks` job. */
+    readonly bootstrap?: boolean;
+    /** T15's embedded verification script; defaults to {@link EMBEDDED_VERIFY_RUNNER_SCRIPT}. */
+    readonly verifyRunnerScript?: string;
+}
+/**
+ * A YAML double-quoted scalar, always.
+ *
+ * Plan §4.5: "a `yamlString()` helper that always double-quotes and escapes, so
+ * the same inputs yield identical bytes on every platform". Everything the
+ * generator interpolates goes through here — including expressions, whose `{`,
+ * `}`, `:` and quotes would otherwise depend on the reader's YAML dialect.
+ */
+declare function yamlString(value: string): string;
+/**
+ * Plan §4.5's branch slug: lower case, `[^a-z0-9._-]` → `-`, runs collapsed,
+ * trimmed to {@link APP_BUILD_BRANCH_SLUG_MAX_CHARS}.
+ */
+declare function branchSlug(branch: string): string;
+/** The image the build publishes (plan §2.4 `EW_IMAGE`, `APP_BUILD_IMAGE_NAME`). */
+declare function buildImageRepository(repository: WorkflowRepositoryInput): string;
+/** The `EW_` secret names a build job writes, space separated — `secret` and not build-service derived (§2.4, §4.11). */
+declare function secretNamesFor(values: readonly BuildValue[]): string[];
+/** The `fromEnv` names the build arguments read, in the order the build block declares them. */
+declare function fromEnvNames(build: AppBuildBlock): string[];
+/** Normalise the App spec's build block: defaults applied, keys sorted (plan §4.5). */
+declare function normaliseBuildBlock(build: AppBuildBlock): CanonicalBuildBlock;
+/** The canonical inputs of one generation — what the header line's fingerprint covers. */
+declare function canonicalInputsFor(input: WorkflowGeneratorInput, verifyRunnerScript: string): CanonicalWorkflowInputs;
+/** The header every generated file carries — plan §2.4:157–159, FR-6. */
+declare function workflowHeader(inputsHash: string): string[];
+/**
+ * Generate the workflow file (plan §2.4).
+ *
+ * Byte-stable by construction: every branch below is a pure function of
+ * {@link WorkflowGeneratorInput}, and the two unordered collections (build args,
+ * services) are emitted in their declared order while the fingerprint sorts them
+ * again for the hash.
+ *
+ * Three shapes come out of it, and the first is T42's:
+ *
+ *   1. **the checks-only file** ({@link checksOnlyFile}) — §4.14, or the empty
+ *      string when no check is left (§4.6 step 8);
+ *   2. **the bootstrap file** (`bootstrap: true`) — dispatch-only, `verify` alone
+ *      (§4.6 step 0);
+ *   3. **the full file** — `build`, `verify` and, when the App spec declares any,
+ *      `checks`.
+ */
+declare function generateWorkflow(input: WorkflowGeneratorInput): string;
+
+/**
+ * APW-05 T8 — the embedded verification script, as the generated workflow
+ * carries it (`run: |` under the "Verify in the runner" step of §2.4).
+ *
+ * ## This is a deliberate interlock shell, not the verification
+ *
+ * Plan §4.3 gives T15 `src/workflow/verify-runner.sh.ts` — "the embedded
+ * verification script as a template literal": the plan schema check, the 12 GiB
+ * refusal, the throwaway dependency containers, the recipe materialisation into a
+ * `0600` env file, the readiness waits, the smoke requests, the shred. **None of
+ * that exists yet.** T8 needs *a* script because §2.4's step list carries the
+ * step and T12/T13's observation and classification paths key off its name
+ * ("Verify in the runner" → `verificationFailed`, plan §4.9 row 10).
+ *
+ * So the constant below does the only honest thing an unfinished script can do:
+ * it **fails loudly**, before touching anything, naming the task that owes the
+ * real one. A verification Build dispatched today ends `failed` with
+ * `EW_VERIFY_NOT_IMPLEMENTED` on its stderr — it does not report success, does not
+ * silently skip the checks the owner asked for, and cannot be mistaken for a
+ * passing verification.
+ *
+ * **T15 replaces this constant's body** (`EMBEDDED_VERIFY_RUNNER_SCRIPT`) and
+ * leaves the name, the export and its use in `generator.ts` alone. Because the
+ * generator hashes the script into the canonical inputs
+ * (`verifyRunnerScriptSha256`), that replacement moves `inputsHash` on its own and
+ * every App Work gets a commit or pull request with the new file on its next
+ * preparation (plan §4.5) — no second place to remember.
+ */
+declare const EMBEDDED_VERIFY_RUNNER_SCRIPT: string;
+
+/**
+ * APW-05 T9 — is the tracked branch protected? (plan §4.6 step 1, `APW05-G16`)
+ *
+ * Two reads, because one is not enough: the classic endpoint
+ * `GET /repos/{o}/{r}/branches/{branch}/protection` answers **404** for a branch
+ * that is protected only by a **ruleset**, so a plugin that trusted it alone would
+ * commit straight into a protected branch. The rules read
+ * (`GET /repos/{o}/{r}/rules/branches/{branch}`, paginated, read access only)
+ * closes that hole.
+ *
+ * The verdict carries **which read decided it**, because "protected" is not a
+ * boolean anyone can act on: a 403 is treated as protected *without* knowing why
+ * (the token cannot see the rules), and the delivery rules of plan §4.6 step 2
+ * then rely on `refRejectedByRule` as the fallback. That distinction is what the
+ * T9 spec asserts, and it is the difference between a branch we know is protected
+ * and one we merely cannot prove is open.
+ *
+ * Nothing here writes, and nothing here throws on a provider refusal: a 403 or a
+ * 404 from either endpoint is an *answer* (the plan's own words: "A 403 or 404
+ * from the rules endpoint means no rules are known locally; the refusal fallback
+ * of step 2 covers that case").
+ */
+/** One endpoint's answer — a status and, when there is one, a body. A refusal is data, not an exception. */
+interface BranchProtectionResponse<T> {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly data?: T;
+}
+/** The fields of the classic protection payload this decision reads (plan §4.6 step 1). */
+interface BranchProtectionPayload {
+    readonly required_pull_request_reviews?: unknown;
+    readonly required_status_checks?: unknown;
+}
+/** One rule from `GET /rules/branches/{branch}` — the fields this decision reads. */
+interface BranchRulePayload {
+    readonly type?: string;
+    /** Present on some payloads; when it is, only `active` counts (plan §4.6 step 1). */
+    readonly enforcement?: string;
+}
+/** The two reads the branch-rules decision needs, and nothing else. */
+interface BranchProtectionPort {
+    readBranchProtection(input: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly branch: string;
+    }): Promise<BranchProtectionResponse<BranchProtectionPayload>>;
+    readBranchRules(input: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly branch: string;
+        readonly page: number;
+    }): Promise<BranchProtectionResponse<readonly BranchRulePayload[]>>;
+}
+/** Which read decided the verdict — the reason, not just the boolean. */
+type BranchProtectionDecision = 'requiredPullRequestReviews' | 'requiredStatusChecks' | 'forbidden' | 'rulesetPullRequest' | 'rulesetStatusChecks' | 'none';
+/** The decision and the read that produced it. */
+interface BranchProtectionVerdict {
+    readonly protected: boolean;
+    readonly decision: BranchProtectionDecision;
+}
+/** The branch coordinates both reads address. */
+interface BranchCoordinates {
+    readonly owner: string;
+    readonly repo: string;
+    readonly branch: string;
+}
+/** Page size for the rules read — GitHub's maximum, so the pagination loop is as short as it can be. */
+declare const BRANCH_RULES_PAGE_SIZE = 100;
+/**
+ * How many rules pages are read before the loop stops.
+ *
+ * A bound, not a guess: an active `pull_request` or `required_status_checks` rule
+ * is almost always on the first page, and a repository with more than a thousand
+ * branch rules is not a case worth hanging a preparation job on. Reaching the cap
+ * without a match answers `unprotected`, which the `refRejectedByRule` fallback
+ * of §4.6 step 2 covers.
+ */
+declare const BRANCH_RULES_MAX_PAGES = 10;
+/** The two rule types plan §4.6 step 1 names. */
+declare const BRANCH_PROTECTION_RULE_TYPES: readonly ["pull_request", "required_status_checks"];
+/**
+ * Decide whether the tracked branch is protected (plan §4.6 step 1).
+ *
+ * Order, and why:
+ *
+ *   1. the classic endpoint — `403` is **protected** (we cannot see the rules, so
+ *      we do not get to assume the branch is open); a `200` protects when either
+ *      `required_pull_request_reviews` or `required_status_checks` is present;
+ *   2. the rules endpoint — consulted on a `404` **and** on a `200` that carried
+ *      neither field, because a ruleset can protect a branch the classic endpoint
+ *      reports as unprotected.
+ */
+declare function isBranchProtected(port: BranchProtectionPort, coordinates: BranchCoordinates): Promise<BranchProtectionVerdict>;
+
+/**
+ * APW-05 T9 — delivering the generated workflow (plan §4.6, `APW05-G16`, R-4).
+ *
+ * ## The one rule that shapes everything here
+ *
+ * **The plugin never clones.** Every write goes through the `RepositoryWriter` the
+ * facade binds (APW-03's `commitFiles?` via `GitFacadeService`), whose four members
+ * are all this file calls: `getFileContent`, `commitFiles`, `createBranch`,
+ * `createPullRequest`. Writing one file must not clone a 1 GB repository
+ * (plan §1.2), and the T9 spec asserts that no clone-shaped call exists — the fake
+ * writer has no clone member to call.
+ *
+ * ## The paths, and which one a branch gets
+ *
+ * | Branch state                                                  | Path                                     |
+ * | ------------------------------------------------------------- | ---------------------------------------- |
+ * | File on the tracked branch already equals the generated bytes  | `unchanged`, **zero write calls**        |
+ * | File exists, its sha256 is neither the stored one nor the new one | **hand edit** → pull request, never an overwrite on the tracked branch (FR-9) |
+ * | `createdByAppWork === false` (a Link relation)                 | pull request, always (R-4)               |
+ * | Protected (reviews, status checks, ruleset, or a 403)          | pull request                             |
+ * | Otherwise                                                      | direct commit onto the tracked branch    |
+ * | **No workflow content** (T42: no build and no check remains)   | pull request — the removal of §4.6 step 8, never a direct commit (FR-70) |
+ *
+ * The pull request path reuses **one** pull request: `ever-works/build-workflow` is
+ * created from the tracked head when absent, the commit lands on it, and the pull
+ * request is then ALWAYS asked for. Reuse is proven by GitHub, never assumed from
+ * a stored number: when an open pull request already exists for that head, the
+ * create is refused with `pullRequestExists` (the contract's code, or GitHub's own
+ * 422 "A pull request already exists" when nothing translated it), and that
+ * refusal is what `pullRequestUpdated` means (ACC-05-02). The stored
+ * `pullRequestNumber`/`pullRequestUrl` are only echoed back so the reused pull
+ * request keeps its link; a stored pull request the owner CLOSED is therefore
+ * replaced by a new one rather than "updated" forever. A second and a third
+ * preparation leave exactly one open pull request, and a preparation whose bytes
+ * are already on that branch commits nothing at all.
+ *
+ * ## The refusals
+ *
+ *   - `nonFastForward` — a race: retry the direct write, at most
+ *     {@link WORKFLOW_WRITE_MAX_ATTEMPTS} attempts in total (plan §4.6 step 2's
+ *     "up to 3 times"), then `blocked workflowWriteFailed`.
+ *   - `refRejectedByRule` — a protection or ruleset the pre-check could not see:
+ *     switch to the pull request path **once** and never retry the direct write.
+ *     If the pull request path is refused the same way, stop with
+ *     `blocked workflowWriteFailed`, detail `{ cause: 'branchRules' }` — never a
+ *     loop. Its copy is "The build workflow could not be written." plus "A rule on
+ *     this repository refuses the change." (plan §4.6 steps 2–3).
+ *   - a read-back that does not match: retried **once**; still mismatched →
+ *     `blocked workflowWriteFailed`, and `storedWorkflowSha256` stays untouched —
+ *     only a matching read-back may store a hash (FR-8).
+ *
+ * ## Where the branch head comes from
+ *
+ * `commitFiles` needs the commit the caller believes the branch is at, and the
+ * `RepositoryWriter` contract has no `getBranch` member. Two ways in, both within
+ * the four:
+ *
+ *   1. `input.resolveTrackedHead` — the facade, which already holds
+ *      `GitFacadeService`, passes the real head (T16's binding);
+ *   2. otherwise {@link readBranchHead} calls `createBranch(branch, branch)`, which
+ *      the contract documents as returning an existing branch rather than
+ *      recreating it — a read that happens to be spelled as a create.
+ *
+ * The head is re-read on **every** attempt, which is what makes the
+ * `nonFastForward` retry real rather than a repeat of the same stale commit.
+ */
+/** The commit message of a file that did not exist (plan §4.6 step 2). */
+declare const WORKFLOW_COMMIT_MESSAGE_ADD = "Add Ever Works build workflow";
+/** The commit message of a file the platform is changing (plan §4.6 step 2). */
+declare const WORKFLOW_COMMIT_MESSAGE_UPDATE = "Update Ever Works build workflow";
+/** The pull request title (plan §4.6 step 3). */
+declare const WORKFLOW_PULL_REQUEST_TITLE = "Add Ever Works build workflow";
+/** The pull request body — what a reviewer is looking at, and what not to do with it. */
+declare const WORKFLOW_PULL_REQUEST_BODY = "Ever Works generated this workflow from the App spec. It builds the image for this App Work on GitHub-hosted runners and publishes it to GHCR. Hand edits to this file are never overwritten: Ever Works proposes its changes as pull requests.";
+/**
+ * How many direct-write attempts are made in total (plan §4.6 step 2: "A
+ * `nonFastForward` error retries from step 1 up to 3 times").
+ *
+ * Read as at most three attempts, which is the stricter of the two readings of
+ * "up to 3 times" and therefore cannot exceed the bound the plan states.
+ */
+declare const WORKFLOW_WRITE_MAX_ATTEMPTS = 3;
+/** How many read-backs one successful write gets: the first, plus the plan's single retry (FR-8). */
+declare const WORKFLOW_READ_BACK_ATTEMPTS = 2;
+/** The tracked branch and the App Work's relation to it. */
+interface WorkflowRepositoryCoordinates {
+    readonly owner: string;
+    readonly repo: string;
+    readonly trackedBranch: string;
+    /** `false` for a Link relation — that repository is not ours to write into (R-4). */
+    readonly createdByAppWork: boolean;
+}
+/** What the caller asks to deliver, and what it remembers from the last delivery. */
+interface WorkflowWriteInput {
+    readonly repository: WorkflowRepositoryCoordinates;
+    /** The generated bytes. */
+    readonly content: string;
+    /** The workflow sha256 the platform last wrote, or `null` — the other half of hand-edit detection (FR-9). */
+    readonly lastWrittenWorkflowSha256: string | null;
+    /**
+     * The pull request the platform recorded for this App Work (§3.1b), when there is one.
+     * Echoed back when GitHub reports an open pull request for the head; never used to
+     * decide that one is open.
+     */
+    readonly pullRequestNumber?: number | null;
+    /** That pull request's URL, echoed back on the reuse path (the writer never re-reads it). */
+    readonly pullRequestUrl?: string | null;
+    /** Overrides {@link APP_BUILD_WORKFLOW_PATH}; exists so a spec can name its own path. */
+    readonly workflowPath?: string;
+    /** The facade's branch-head read (T16). Without it, {@link readBranchHead} is used. */
+    readonly resolveTrackedHead?: () => Promise<string>;
+}
+/** What the delivery decided — the transport state §3.1b maps onto `workflowState`. */
+interface WorkflowWriteResult {
+    /**
+     * The delivery outcome.
+     *
+     * `'blocked'` is this writer's own terminal state and is **not** a member of
+     * `PrepareRepositoryResult.workflow.state` (which has five): the caller maps it
+     * onto `PrepareRepositoryResult.blocked` with reason `workflowWriteFailed`, and
+     * must not pass it through as a stored workflow state.
+     */
+    readonly state: 'unchanged' | 'committed' | 'pullRequestOpened' | 'pullRequestUpdated' | 'editedByHand' | 'blocked';
+    readonly commitSha?: string;
+    readonly pullRequestNumber?: number;
+    readonly pullRequestUrl?: string;
+    /**
+     * The sha256 the platform may store as `lastWrittenWorkflowSha256`, or `null`
+     * when nothing on the tracked branch has been proven to equal the generated
+     * bytes. Only a matching read-back sets it (FR-8, plan §4.6 step 4).
+     */
+    readonly storedWorkflowSha256: string | null;
+    readonly blocked?: {
+        readonly reason: 'workflowWriteFailed';
+        readonly detail: {
+            readonly cause: string;
+        };
+    };
+}
+/** The refusal code of a thrown write error, if it is one of the codes the contract names. */
+declare function repositoryWriteErrorCode(error: unknown): RepositoryWriteErrorCode | null;
+/**
+ * Deliver the generated workflow (plan §4.6).
+ *
+ * `protection` is the branch-rules port; leave it out when the caller has no
+ * protection read (a fork the platform owns, a spec), in which case only
+ * `createdByAppWork` and hand-edit detection decide the path.
+ *
+ * **Empty content is T42's removal request** (plan §4.6 step 8, FR-70): the
+ * generator answers `''` when neither a build nor a check remains, and
+ *
+ *   - with no file on the tracked branch there is nothing to remove — no write, no
+ *     pull request, `unchanged` (and no stored hash: nothing was proven);
+ *   - with one, the removal is **proposed by pull request** and never committed to
+ *     the tracked branch: §4.6 step 8's "never deleted directly". The branch
+ *     protections of steps 1–2 are not consulted, because there is no direct path
+ *     to protect; `createdByAppWork` and the hand-edit verdict still decide the
+ *     state the caller stores (§3.1b).
+ */
+declare function writeWorkflow(input: WorkflowWriteInput, writer: RepositoryWriter, protection?: BranchProtectionPort): Promise<WorkflowWriteResult>;
+
+export { ACTION_PINS, ACTION_PIN_SHA_PATTERN, type ActionPin, type ActionPinKey, BRANCH_PROTECTION_RULE_TYPES, BRANCH_RULES_MAX_PAGES, BRANCH_RULES_PAGE_SIZE, type BranchCoordinates, type BranchProtectionDecision, type BranchProtectionPayload, type BranchProtectionPort, type BranchProtectionResponse, type BranchProtectionVerdict, type BranchRulePayload, type BuildValueSecretSync, type BuildValueSyncInput, type BuildValueSyncResult, CANONICAL_INPUT_FIELDS, type CanonicalBuildArg, type CanonicalBuildBlock, type CanonicalBuildService, type CanonicalBuildValue, type CanonicalCheck, type CanonicalRunner, type CanonicalSettings, type CanonicalWorkflowInputs, EMBEDDED_VERIFY_RUNNER_SCRIPT, GENERATOR_RESERVED_LITERALS, GITHUB_ACTIONS_BUILD_PLATFORM_MANAGED_KEYS, GITHUB_ACTIONS_BUILD_SETTING_DEFAULTS, GITHUB_ACTIONS_BUILD_SETTING_KEYS, GITHUB_SECRET_NAME_PATTERN, GitHubActionsBuildPlugin, type GitHubActionsBuildSettingKey, type GitHubActionsBuildSettings, type GitHubActionsBuildSettingsSchema, LARGER_RUNNER_LABEL_PATTERN, LARGER_RUNNER_MEMORY_MAX_GIB, LARGER_RUNNER_MEMORY_MIN_GIB, LARGER_RUNNER_VCPU_MAX, LARGER_RUNNER_VCPU_MIN, PREPARATION_STATE_KEYS, type PlatformManagedJsonSchema, type RepositorySecretPort, type SecretSyncDependencies, type SecretSyncLogger, type VerifyPromptedSecretResult, WORKFLOW_COMMIT_MESSAGE_ADD, WORKFLOW_COMMIT_MESSAGE_UPDATE, WORKFLOW_PULL_REQUEST_BODY, WORKFLOW_PULL_REQUEST_TITLE, WORKFLOW_READ_BACK_ATTEMPTS, WORKFLOW_WRITE_MAX_ATTEMPTS, type WorkflowCheckInput, type WorkflowGeneratorInput, type WorkflowRepositoryCoordinates, type WorkflowRepositoryInput, type WorkflowRunnerInput, type WorkflowSettingsInput, type WorkflowWriteInput, type WorkflowWriteResult, actionPin, actionPinReference, branchSlug, buildImageRepository, buildSecretName, canonicalActionPins, canonicalCheck, canonicalInputsFor, canonicalWorkflowJson, canonicaliseWorkflowInputs, checkTimeoutMinutes, computeWorkflowInputsHash, createBuildValueSecretSync, GitHubActionsBuildPlugin as default, fromEnvNames, generateWorkflow, gitHubActionsBuildSettingsSchema, isBranchProtected, isSecretLimitError, isValidGitHubSecretName, loadSodium, normaliseBuildBlock, notImplemented, repositoryWriteErrorCode, sealSecretValue, secretNamesFor, workflowHeader, writeWorkflow, yamlString };