@effected/github-actions 0.1.0 → 0.3.0

package/index.d.ts

@@ -2,7 +2,9 @@ import { NodeServices } from "@effect/platform-node";
 import { Cause, Config, ConfigProvider, Context, Duration, Effect, FileSystem, Layer, Logger, Option, Path, Redacted, Result, Schema } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
+import { IdentityToken, SlsaProvenance } from "@effected/sbom";
 import { BotIdentity, GitHubApp, GitHubClient, InstallationToken, PermissionLevel, RetryPolicy } from "@effected/github";
+import { PackageManagerPin } from "@effected/npm";
 //#region src/ActionEnvironment.d.ts
 declare const ActionEnvironmentError_base: Schema.Class<ActionEnvironmentError, Schema.TaggedStruct<"ActionEnvironmentError", {
   readonly reason: Schema.Literals<readonly ["missing", "malformed"]>;
@@ -237,6 +239,24 @@ declare class WorkflowCommand {
 }
 //#endregion
 //#region src/ActionLogger.d.ts
+/**
+ * Options for {@link ActionLoggerShape.withBuffer}.
+ *
+ * @public
+ */
+interface WithBufferOptions {
+  /**
+   * What happens to the captured transcript when the step **succeeds**.
+   *
+   * @remarks
+   * `"flush"` — the default — replays it, so a clean run still prints what it
+   * did. `"discard"` drops it, which is what keeps a green release log to one
+   * line per step: the transcript exists only as the failure report. A failure,
+   * a defect or an interruption flushes under either setting — the choice is
+   * only about what a success is worth in the log.
+   */
+  readonly onSuccess?: "flush" | "discard";
+}
 /**
  * The {@link ActionLogger} service shape.
  *
@@ -252,13 +272,18 @@ interface ActionLoggerShape {
    * Warnings and errors are **not** buffered — they go out as they happen, so a
    * long step still reports trouble while it is running. Everything at `Info`
    * and below is held and flushed on every exit path, including a defect or an
-   * interruption, so a clean run still prints its transcript.
+   * interruption, so a clean run still prints its transcript. A step that
+   * should be **quiet** when it succeeds passes
+   * `{ onSuccess: "discard" }` ({@link WithBufferOptions}); failure still
+   * spills the transcript either way.
    *
    * Buffering is skipped entirely when the runner has step debugging enabled or
    * the ambient minimum log level is already `Debug` or lower — someone asking
-   * for verbose output wants it live.
+   * for verbose output wants it live, and that overrides
+   * `onSuccess: "discard"` too: asking for debug output means wanting to see
+   * what a green step did.
    */
-  readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>, options?: WithBufferOptions) => Effect.Effect<A, E, R>;
   /**
    * Emit a `::notice::` annotation.
    *
@@ -349,9 +374,11 @@ declare const ActionOutputError_base: Schema.Class<ActionOutputError, Schema.Tag
    * the code is running outside a GitHub runner. `writeFailed` — the file
    * exists but could not be appended to. `invalidName` — the name would
    * corrupt the file's block structure. `encodeFailed` — a value did not
-   * satisfy its schema.
+   * satisfy its schema. `detached` — the member was called under
+   * {@link ActionOutputs.layerDetached}, where the channel it writes cannot
+   * reach the job that would read it.
    */
-  readonly reason: Schema.Literals<readonly ["unavailable", "writeFailed", "invalidName", "encodeFailed"]>;
+  readonly reason: Schema.Literals<readonly ["unavailable", "writeFailed", "invalidName", "encodeFailed", "detached"]>;
   /** Which runner file was involved, by environment variable name. */
   readonly file: Schema.optionalKey<Schema.String>;
   /** The output or variable name, when one is involved. */
@@ -381,7 +408,17 @@ interface ActionOutputsShape {
   readonly summary: (content: string) => Effect.Effect<void, ActionOutputError>;
   /** Export an environment variable to **subsequent** steps. */
   readonly exportVariable: (name: string, value: string) => Effect.Effect<void, ActionOutputError>;
-  /** Prepend a directory to `PATH` for subsequent steps. */
+  /**
+   * Prepend a directory to `PATH` for **subsequent** steps.
+   *
+   * @remarks
+   * This appends to the `GITHUB_PATH` runner file and does **nothing else** —
+   * unlike `@actions/core`, it does NOT mutate the live `process.env.PATH` of
+   * the current process. A same-process probe of a tool that was just added
+   * (`pnpm --version`, a shim, a binary) will not find it by name; probe by
+   * absolute path instead. The runner applies the addition when the next step
+   * starts, exactly as it does for {@link ActionOutputsShape.exportVariable}.
+   */
   readonly addPath: (path: string) => Effect.Effect<void, ActionOutputError>;
   /** Emit an error annotation. Does not itself set the exit code. */
   readonly setFailed: (message: string) => Effect.Effect<void>;
@@ -406,6 +443,45 @@ declare const ActionOutputs_base: Context.ServiceClass<ActionOutputs, "@effected
  */
 declare class ActionOutputs extends ActionOutputs_base {
   static readonly layer: Layer.Layer<ActionOutputs, never, ActionEnvironment | FileSystem.FileSystem>;
+  /**
+   * The outputs surface that is correct inside a **detached worker**.
+   *
+   * @remarks
+   * The masking model assumes the runner parses stdout. A detached worker's
+   * stdout is a **log file no runner parses**, so under the real layer
+   * `setSecret` emits `::add-mask::<plaintext>` into that file — a command
+   * that is simultaneously **inert** (nothing reads it, so nothing is masked)
+   * and a **secret leak** (the plaintext is now sitting verbatim in a log). A
+   * production action shipped exactly that for one round: an S3 secret and
+   * session token written into a worker's log by the masking call itself.
+   * This layer is the worker-side fix; the parent-side rule is that every
+   * secret a worker will hold is masked **before** the spawn, by
+   * `Secret.forChildEnv` under the real layer.
+   *
+   * The layer needs no environment and no filesystem — its `R` is `never` —
+   * so a worker composing it structurally *cannot* write a runner file.
+   * Per-member behavior:
+   *
+   * - **`setSecret` — silent no-op.** The value must not be written
+   *   *anywhere*: there is no runner on this channel to hand it to, and any
+   *   spelling of it in the log IS the leak. Masking is the parent's job,
+   *   before the worker exists.
+   * - **`set`, `setJson`, `exportVariable`, `addPath`, `summary` — fail
+   *   typed** (`reason: "detached"`, naming the file). Each writes a runner
+   *   file that configures the parent job's *later steps* — `GITHUB_OUTPUT`,
+   *   `GITHUB_ENV`, `GITHUB_PATH` — or is collected when the step completes
+   *   (`GITHUB_STEP_SUMMARY`). A detached worker has no later steps, may
+   *   outlive the job entirely, and even an inherited file path would be
+   *   read at a moment unrelated to the write — so a worker calling one of
+   *   these is a program error worth surfacing, not a write to degrade
+   *   silently.
+   * - **`setFailed` — degrades to a plain log line** (`Console.error`,
+   *   without the `::error::` syntax nothing here would parse). Unlike the
+   *   file members it is log-like: "record that something failed" still
+   *   means something in a worker's log, and its signature carries no error
+   *   channel to fail through.
+   */
+  static readonly layerDetached: Layer.Layer<ActionOutputs>;
   /** A test double. Unstubbed members die rather than silently succeeding. */
   static readonly makeTest: (overrides?: Partial<ActionOutputsShape>) => ActionOutputsShape;
   /** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
@@ -417,10 +493,13 @@ declare const ActionStateError_base: Schema.Class<ActionStateError, Schema.Tagge
   /**
    * `missing` — no value was saved under this key in an earlier phase.
    * `malformed` — a value is there but is not JSON, or does not satisfy the
-   * schema it was read with. `writeFailed` — the state file could not be
+   * schema it was read with. `notPlainJson` — caught at SAVE time: the
+   * schema's encoded form does not survive `JSON.stringify`/`JSON.parse`, so
+   * persisting it would present one phase later as a `malformed` mystery with
+   * no pointer to the cause. `writeFailed` — the state file could not be
    * appended to.
    */
-  readonly reason: Schema.Literals<readonly ["missing", "malformed", "writeFailed"]>;
+  readonly reason: Schema.Literals<readonly ["missing", "malformed", "notPlainJson", "writeFailed"]>;
   readonly key: Schema.String;
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
@@ -438,7 +517,24 @@ declare class ActionStateError extends ActionStateError_base {
  * @public
  */
 interface ActionStateShape {
-  /** Persist a value for a later phase. */
+  /**
+   * Persist a value for a later phase.
+   *
+   * @remarks
+   * **The schema's ENCODED form must be plain JSON** — `GITHUB_STATE` is a
+   * text file and the value crosses it as `JSON.stringify(encoded)`. A schema
+   * whose encoded side is a class instance (`Schema.Option`'s is an `Option`,
+   * serialized via its `toJSON` to `{"_id":"Option",…}`) writes something no
+   * later phase can decode; use the plain-JSON codec instead —
+   * `Schema.OptionFromNullOr` for an optional value.
+   *
+   * Every save proves the rule: the encoded value is round-tripped through
+   * `JSON.stringify`/`JSON.parse` and re-decoded, and a value that does not
+   * survive fails HERE, typed (`reason: "notPlainJson"`, naming the key) —
+   * rather than one phase later as a `malformed` mystery in `post` that
+   * `main` believed it saved. Action state is small by protocol, so the
+   * per-save round-trip costs effectively nothing.
+   */
   readonly save: <A, I>(key: string, value: A, schema: Schema.Codec<A, I>) => Effect.Effect<void, ActionStateError>;
   /** Read a value saved by an earlier phase. */
   readonly get: <A, I>(key: string, schema: Schema.Codec<A, I>) => Effect.Effect<A, ActionStateError>;
@@ -685,6 +781,14 @@ declare class CacheKeyError extends CacheKeyError_base {
 declare const CacheKey_base: Schema.Class<CacheKey, Schema.Struct<{
   /** The components, most general first. */
   readonly segments: Schema.NonEmptyArray<Schema.String>;
+  /**
+   * The explicit ladder policy, when one was given: how many leading
+   * segments each rung keeps, in the order the rungs are tried. Absent for
+   * the default every-prefix ladder; **empty for no ladder at all** —
+   * exact-match-only. See {@link CacheKey.withRestoreDepths} and
+   * {@link CacheKey.withoutRestoreKeys}.
+   */
+  readonly restoreDepths: Schema.optionalKey<Schema.$Array<Schema.Number>>;
 }>, {}>;
 /**
  * A GitHub Actions cache key and the restore-key ladder that goes with it.
@@ -697,6 +801,12 @@ declare const CacheKey_base: Schema.Class<CacheKey, Schema.Struct<{
  * the primary key and its fallbacks impossible to drift apart, which is the
  * failure that produces a cache that never hits and never says why.
  *
+ * By default every prefix is a rung. When some segments must never be dropped
+ * — a rung without a version digest resurrects stale cross-version caches —
+ * give the key an explicit ladder policy with
+ * {@link CacheKey.withRestoreDepths}, or none at all with
+ * {@link CacheKey.withoutRestoreKeys}, instead of bypassing the typed key.
+ *
  * @example
  * ```ts
  * import { CacheKey } from "@effected/github-actions";
@@ -715,12 +825,69 @@ declare class CacheKey extends CacheKey_base {
    * The restore keys, most specific first.
    *
    * @remarks
-   * Each rung drops the last segment and keeps the trailing separator, so a
-   * three-segment key falls back to two prefixes and a one-segment key falls
-   * back to nothing — there is no rung that would match every cache in the
-   * repository.
+   * By default each rung drops the last segment and keeps the trailing
+   * separator, so a three-segment key falls back to two prefixes and a
+   * one-segment key falls back to nothing — there is no rung that would match
+   * every cache in the repository.
+   *
+   * **The default ladder is every prefix**, which is wrong for a key whose
+   * later segments must never be dropped alone: a
+   * `platform-arch-versionHash-branchHash-lockfileHash` key derives rungs
+   * without the version digest, and those resurrect stale cross-version
+   * caches. A key built with {@link CacheKey.withRestoreDepths} carries its
+   * own ladder instead, and this getter answers exactly that ladder — so
+   * `ActionCache.restore` picks the policy up through the same typed-key
+   * path, no hand-built restore-key list required. An **empty** policy
+   * ({@link CacheKey.withoutRestoreKeys}) answers no rungs at all: only
+   * *absence* selects the default ladder, so "none" is never mistaken for
+   * "every prefix".
    */
   get restoreKeys(): ReadonlyArray<string>;
+  /**
+   * A copy of this key carrying an explicit restore-key ladder policy.
+   *
+   * @remarks
+   * Each depth is the number of **leading segments** the rung keeps, and the
+   * rungs are emitted in exactly the order given — GitHub tries restore keys
+   * in order, so the order IS the policy. Descending depths (most specific
+   * first) are what a fallback ladder almost always wants; that convention is
+   * recommended rather than enforced, because rung ordering is the consumer's
+   * policy where commas, newlines and the length limit are the runner's
+   * protocol. A depth outside `1..segments.length - 1` is refused at
+   * construction: `0` would match every cache in the repository, and
+   * `segments.length` would just repeat the primary key.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   *
+   * const key = CacheKey.of("Linux", "X64", "v1hash", "main", "lockhash").withRestoreDepths([4, 3]);
+   * key.restoreKeys; // ["Linux-X64-v1hash-main-", "Linux-X64-v1hash-"]
+   * ```
+   */
+  withRestoreDepths(depths: readonly [number, ...Array<number>]): CacheKey;
+  /**
+   * A copy of this key that restores from its **exact key only** — no ladder.
+   *
+   * @remarks
+   * The third point in the policy space, and the one the typed key had no
+   * spelling for: absence of a policy means the default every-prefix ladder,
+   * so exact-match-only restores (a cache-bust mode, where a stale partial
+   * hit is worse than a cold start) previously forced the caller back to the
+   * string form. This is the same `restoreDepths` field carrying **zero
+   * rungs** — an honest value, not a sentinel: `ActionCache.restore` sends no
+   * `restore_keys` at all, so the backend answers this key or a miss.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   *
+   * const key = CacheKey.of("Linux", "pnpm-store", "abc123").withoutRestoreKeys();
+   * key.key;          // "Linux-pnpm-store-abc123"
+   * key.restoreKeys;  // []
+   * ```
+   */
+  withoutRestoreKeys(): CacheKey;
   /** Build a key from its segments. */
   static of(...segments: readonly [string, ...ReadonlyArray<string>]): CacheKey;
   /**
@@ -866,9 +1033,31 @@ declare class ActionCacheError extends ActionCacheError_base {
  */
 interface ActionCacheShape {
   /**
-   * Archive `paths` and store them under `key`.
+   * Archive the files and directories matching `paths` and store them under
+   * `key`.
    *
    * @remarks
+   * `paths` is a list of glob **patterns**, resolved with `actions/cache`
+   * parity before `tar` ever sees them: a pattern may match directories (a
+   * matched directory is archived recursively, never expanded into its
+   * descendants), a pattern that matches nothing — including a literal path
+   * that is not on disk — is silently dropped, and a list that resolves to
+   * nothing at all fails typed rather than reserving an entry no archive will
+   * ever back. A leading `~` expands to the caller's home directory, relative
+   * patterns root at `GITHUB_WORKSPACE` (falling back to the working
+   * directory), and a leading `!` marks an exclusion.
+   *
+   * The entry **version** is a digest of the literal pattern list, exactly as
+   * `actions/cache` computes it — resolution feeds `tar` only, never the
+   * version — so {@link ActionCacheShape.restore | restore}, which resolves
+   * nothing, derives the same version from the same list for free.
+   *
+   * One deliberate divergence from the toolkit: where `actions/cache` re-roots
+   * every match relative to the workspace, resolved paths here stay
+   * **absolute** and are archived with `tar -P`, so a restore puts every file
+   * back where it came from regardless of the restoring step's working
+   * directory.
+   *
    * A key that already exists is a **success**: cache entries are immutable, so
    * another job having written it first is the outcome the caller wanted.
    */
@@ -881,6 +1070,11 @@ interface ActionCacheShape {
    * `Option.none()` is a miss, not a failure — a cold cache is the normal state
    * of a new branch. Passing a {@link CacheKey} supplies its restore-key ladder
    * automatically; passing a `string` and no ladder means "this key or nothing".
+   *
+   * `paths` only derives the entry version and MUST be the same literal list
+   * the save used — no glob resolution happens here, because none is needed:
+   * extraction consumes no path list (the archive already names its contents),
+   * and `actions/cache` likewise hashes the un-resolved list on both sides.
    */
   readonly restore: (paths: ReadonlyArray<string>, key: string | CacheKey, restoreKeys?: ReadonlyArray<string>) => Effect.Effect<Option.Option<string>, ActionCacheError>;
 }
@@ -987,6 +1181,21 @@ declare class ActionCache extends ActionCache_base {
  */
 declare class ActionInput {
   private constructor();
+  /**
+   * The exact environment variable the runner publishes an input under.
+   *
+   * @remarks
+   * `variable("biome-version")` is `"INPUT_BIOME-VERSION"` — GitHub
+   * uppercases, replaces **spaces** with underscores, and leaves every other
+   * character (**dashes included**) alone. This is the same derivation every
+   * accessor on this class resolves through, exported so a test that must
+   * spell a runner variable can derive it instead of hand-writing it: a
+   * hand-written `INPUT_BIOME_VERSION` reads as absent on a real runner, the
+   * default silently applies, and the suite goes green against the wrong
+   * value. Prefer keying the test environment by input name (see
+   * {@link ActionInput.provider}) so no variable is spelled at all.
+   */
+  static readonly variable: (name: string) => string;
   /**
    * A required string input.
    *
@@ -1096,14 +1305,37 @@ declare class ActionInput {
    */
   static schema<A, I>(name: string, schema: Schema.Codec<A, I>): Config.Config<A>;
   /**
-   * A `ConfigProvider` over a record of runner variables.
+   * A `ConfigProvider` over a record of runner variables **or input names**.
    *
    * @remarks
-   * Subsumes the source package's free-standing `ActionsConfigProvider`, whose
-   * three behaviors are preserved exactly: the path is joined with `_`, spaces
-   * become underscores and the whole is uppercased; and an **empty string
-   * reads as absent**, because the runner sets unsupplied inputs to `""` and
-   * treating that as present would make every optional input look supplied.
+   * The record dual-accepts, and the split is the `INPUT_` prefix:
+   *
+   * - A key already spelled as a runner variable (`INPUT_BIOME-VERSION`,
+   *   `PLAIN_VAR`) is read verbatim, exactly as before.
+   * - Any other key is treated as an **input name**, `with:`-block style —
+   *   `{ "biome-version": "2.3.14" }` — and serves the variable this module
+   *   derives for it (`ActionInput.variable`). This is the spelling to
+   *   prefer in tests: a hand-written `INPUT_BIOME_VERSION` (underscore where
+   *   the runner keeps the dash) reads as absent and the default silently
+   *   applies, and the input-name form makes that class of bug
+   *   unrepresentable — the mangling never leaves this module.
+   *
+   * When both spellings of the same input are present and non-empty, the
+   * explicit `INPUT_`-spelled entry wins.
+   *
+   * A **flat single-segment** lookup additionally tries the `INPUT_`
+   * derivation of the name first, mirroring the order the production runtime
+   * installs ({@link ActionInput.providerOver} via `layerDefault`) — so a
+   * bare `Config.string("biome-version")` resolves under this provider
+   * exactly as it does inside `Action.run`. Nested and numeric paths pass
+   * through as the joined spelling only, as ever.
+   *
+   * The source package's `ActionsConfigProvider` behaviors are otherwise
+   * preserved exactly: the path is joined with `_`, spaces become underscores
+   * and the whole is uppercased; and an **empty string reads as absent**,
+   * because the runner sets unsupplied inputs to `""` and treating that as
+   * present would make every optional input look supplied. That rule applies
+   * to input-name entries too: `{ "flag": "" }` is an unsupplied input.
    *
    * Taking the environment as an argument rather than reading `process.env`
    * is what makes inputs testable without mutating the test process.
@@ -1176,6 +1408,288 @@ declare class ActionInput {
   static readonly layerDefault: Layer.Layer<never>;
 }
 //#endregion
+//#region src/OidcTokenIssuer.d.ts
+declare const OidcTokenError_base: Schema.Class<OidcTokenError, Schema.TaggedStruct<"OidcTokenError", {
+  /**
+   * `unavailable` — the runner did not publish the token-service variables,
+   * which almost always means the workflow is missing `permissions: id-token:
+   * write`. `requestFailed` — the token service could not be reached or refused
+   * the request. `malformedResponse` — it answered with something that is not a
+   * token envelope. `malformedToken` — the token is not a decodable JWT.
+   * `missingClaims` — it decoded, but without the claims a provenance statement
+   * needs.
+   */
+  readonly reason: Schema.Literals<readonly ["unavailable", "requestFailed", "malformedResponse", "malformedToken", "missingClaims"]>;
+  /** What was wrong, in one line. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** The HTTP status, when the token service answered. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when an OIDC token cannot be issued or read.
+ *
+ * @public
+ */
+declare class OidcTokenError extends OidcTokenError_base {
+  get message(): string;
+}
+declare const OidcClaims_base: Schema.Class<OidcClaims, Schema.Struct<{
+  /** The issuer, e.g. `https://token.actions.githubusercontent.com`. */
+  readonly iss: Schema.String;
+  /** The full ref the workflow ran on. */
+  readonly ref: Schema.String;
+  /** The commit. */
+  readonly sha: Schema.String;
+  /** `owner/repo`. */
+  readonly repository: Schema.String;
+  /** The event that triggered the run. */
+  readonly event_name: Schema.String;
+  /** The reusable-workflow ref, which is what a verifier pins against. */
+  readonly job_workflow_ref: Schema.String;
+  /** The calling workflow's ref. */
+  readonly workflow_ref: Schema.String;
+  /** The numeric repository id, as a string. */
+  readonly repository_id: Schema.String;
+  /** The numeric owner id, as a string. */
+  readonly repository_owner_id: Schema.String;
+  /** `github-hosted` or `self-hosted`. */
+  readonly runner_environment: Schema.String;
+  /** The run id, as a string. */
+  readonly run_id: Schema.String;
+  /** The run attempt, as a string. */
+  readonly run_attempt: Schema.String;
+}>, {}>;
+/**
+ * The claims a GitHub Actions OIDC token carries about the workflow that ran.
+ *
+ * @remarks
+ * The field names are GitHub's own JWT claim names, kept verbatim rather than
+ * translated to the kit's casing. They are an **external vocabulary** — the
+ * same strings that appear in a SLSA provenance predicate and in every
+ * published example of an Actions OIDC policy — and renaming them would put a
+ * translation layer between a consumer and the specification they are reading.
+ *
+ * @public
+ */
+declare class OidcClaims extends OidcClaims_base {}
+/**
+ * The {@link OidcTokenIssuer} service shape.
+ *
+ * @public
+ */
+interface OidcTokenIssuerShape {
+  /**
+   * Request an ID token, optionally bound to an audience.
+   *
+   * @remarks
+   * Omitting the audience sends no `audience` parameter at all, matching
+   * `@actions/core.getIDToken` — the runner's default audience is not the empty
+   * string.
+   */
+  readonly token: (audience?: string) => Effect.Effect<Redacted.Redacted<string>, OidcTokenError>;
+  /**
+   * The token's claims, decoded.
+   *
+   * @remarks
+   * **The signature is deliberately not verified**, for three reasons that are
+   * recorded so nobody "fixes" it:
+   *
+   * 1. The token comes from the runner's own token-service endpoint over TLS.
+   *    The transport is the trust boundary, and the process asking for the
+   *    token is the process that received it.
+   * 2. The claims populate a provenance predicate, not a trust decision.
+   *    Nothing branches on them for authorization; they are recorded as
+   *    attested facts about the workflow that ran.
+   * 3. Verifying would need a JWKS fetch, which turns a decode into a network
+   *    call — untestable without a fixture server, and dependent on GitHub's
+   *    key endpoint being reachable at attestation time.
+   *
+   * A consumer that needs a *verified* token needs a different operation with a
+   * different name and a different error channel, not an option on this one.
+   *
+   * Claims are on the surface rather than left to the call site because that is
+   * what makes the provenance path reachable in a test: a double built with
+   * {@link OidcTokenIssuer.layerFor} answers with real, decodable claims, where
+   * the synthetic non-JWT its predecessor returned made every consumer's
+   * `decodeJwtClaims` yield nothing and silently skipped the path under test.
+   */
+  readonly claims: (audience?: string) => Effect.Effect<OidcClaims, OidcTokenError>;
+}
+declare const OidcTokenIssuer_base: Context.ServiceClass<OidcTokenIssuer, "@effected/github-actions/OidcTokenIssuer", OidcTokenIssuerShape>;
+/**
+ * The runner's OIDC token service.
+ *
+ * @remarks
+ * Lives here rather than with attestation because it reads
+ * `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL`, which
+ * exist only when a workflow declares `permissions: id-token: write` — that is
+ * a fact about the runner, not about signing.
+ *
+ * @example
+ * ```ts
+ * import { OidcTokenIssuer } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const issuer = yield* OidcTokenIssuer;
+ *   const claims = yield* issuer.claims("sigstore");
+ *   return claims.job_workflow_ref;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class OidcTokenIssuer extends OidcTokenIssuer_base {
+  static readonly layer: Layer.Layer<OidcTokenIssuer, never, ActionEnvironment | HttpClient.HttpClient>;
+  /**
+   * An **unsigned** JWT carrying these claims.
+   *
+   * @remarks
+   * For building test doubles, and nothing else: the signature segment is a
+   * placeholder, so this token would fail any verifier. It exists because the
+   * alternative — a double returning a synthetic non-JWT — is what made the
+   * provenance path structurally unreachable in the source package, drawing
+   * four separate apologetic comments from one consumer.
+   */
+  static readonly unsignedTokenFor: (claims: OidcClaims) => Redacted.Redacted<string>;
+  /** A test double. Unstubbed members die rather than answering with a non-token. */
+  static readonly makeTest: (overrides?: Partial<OidcTokenIssuerShape>) => OidcTokenIssuerShape;
+  /** {@link OidcTokenIssuer.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<OidcTokenIssuerShape>) => Layer.Layer<OidcTokenIssuer>;
+  /**
+   * A double that answers with these claims, consistently on both members.
+   *
+   * @remarks
+   * `token()` returns a real decodable JWT built from the same claims
+   * `claims()` returns, so a consumer that decodes the token itself and a
+   * consumer that asks the service both see the same thing. A double whose two
+   * members can disagree is how a test proves a path works while production
+   * takes the other one.
+   */
+  static readonly layerFor: (claims: OidcClaims) => Layer.Layer<OidcTokenIssuer>;
+}
+//#endregion
+//#region src/ActionsIdentityToken.d.ts
+/**
+ * The Actions side of `@effected/sbom`'s inverted OIDC contract.
+ *
+ * @remarks
+ * `@effected/sbom` declares `IdentityToken` — one method, one audience,
+ * one redacted token — precisely so that signing does not drag the Actions
+ * runtime into every consumer that only wants to emit an SBOM. This is the
+ * layer that closes the inversion from the other side: it serves that contract
+ * from the runner's own OIDC token service ({@link OidcTokenIssuer}), the same
+ * arrangement as `@effected/workspaces` implementing `@effected/commands`'
+ * `LocalExec`.
+ *
+ * The audience is forwarded verbatim. `SigstoreSigner` asks its identity
+ * contract for the `sigstore` audience itself (`SIGSTORE_OIDC_AUDIENCE` is the
+ * signing protocol's requirement, owned there), so nothing here — and nothing
+ * in a consumer — needs to spell it.
+ *
+ * An `OidcTokenError` is rewrapped as `IdentityTokenError` with the
+ * original preserved structurally in `cause`, so a refused exchange still says
+ * which audience it was minting for **and** why the runner declined —
+ * `reason: "unavailable"` almost always means the workflow is missing
+ * `permissions: id-token: write`.
+ *
+ * @example
+ * ```ts
+ * import { ActionsIdentityToken, OidcTokenIssuer } from "@effected/github-actions";
+ * import { SigstoreSigner } from "@effected/sbom";
+ * import { Layer } from "effect";
+ *
+ * const signing = SigstoreSigner.layer.pipe(
+ *   Layer.provide(ActionsIdentityToken.layer),
+ *   Layer.provide(OidcTokenIssuer.layer),
+ * );
+ * ```
+ *
+ * @public
+ */
+declare class ActionsIdentityToken {
+  private constructor();
+  /**
+   * `IdentityToken` served by the runner's OIDC token service.
+   *
+   * @remarks
+   * Requires {@link OidcTokenIssuer} rather than composing
+   * `OidcTokenIssuer.layer` in, so an action that already wired the issuer —
+   * every action using `ActionRuntime.layer` has its requirements at hand —
+   * does not construct a second one.
+   */
+  static readonly layer: Layer.Layer<IdentityToken, never, OidcTokenIssuer>;
+}
+//#endregion
+//#region src/ActionsProvenance.d.ts
+/**
+ * The Actions side of `@effected/sbom`'s SLSA provenance constructor.
+ *
+ * @remarks
+ * `SlsaProvenance.forGitHubWorkflow` is total and does the real work, but it
+ * takes a camelCase input record — and the only input anyone inside a workflow
+ * actually holds is the runner's own OIDC claims, spelled in GitHub's
+ * snake_case claim names. The rename between the two is eleven all-string
+ * fields, so transposing `repository_id` and `repository_owner_id` compiles,
+ * passes every type check, and produces a validly signed attestation asserting
+ * the **wrong** provenance. This module owns that rename once, on the same
+ * `github-actions` ↔ `sbom` seam as {@link ActionsIdentityToken}: `sbom` must
+ * not depend on the Actions runtime, so the adapter lives here, beside the
+ * services it reads.
+ *
+ * The construct ends at the predicate. Assembling the in-toto statement,
+ * signing it and uploading the bundle stay with the consumer — that pipeline
+ * is deliberately consumer glue (see `@effected/sbom`'s `SigstoreSigner` and
+ * `@effected/github`'s `Attestation.upload`).
+ *
+ * @example
+ * ```ts
+ * import { ActionsProvenance } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const provenance = yield* ActionsProvenance.capture();
+ *   return provenance.runDetails.builder.id;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ActionsProvenance {
+  private constructor();
+  /**
+   * The current run's SLSA provenance, built from the runner's OIDC claims.
+   *
+   * @remarks
+   * Every field `GitHubWorkflowProvenance` declares is populated from
+   * {@link OidcClaims}, except `serverUrl`, which is read from
+   * `GITHUB_SERVER_URL` through {@link ActionEnvironment}'s `getOptional`
+   * with `https://github.com` as the default — **not** through the
+   * `GitHubContext` projection. The projection fails typed when a `GITHUB_*`
+   * variable is missing, and a missing server URL is not a failure: it has a
+   * correct default. GHES consumers set the variable, github.com consumers
+   * never should have to, and neither should think about it. (Upstream
+   * `@actions/attest` reads the same variable with no default and writes the
+   * literal string `undefined` into every URL it builds — the hazard
+   * `GitHubWorkflowProvenance.serverUrl` being a required field exists to
+   * prevent.)
+   *
+   * The audience is forwarded to {@link OidcTokenIssuerShape.claims}
+   * verbatim; the claims a provenance reads do not depend on it, so omitting
+   * it is fine and spends no extra token mint.
+   *
+   * An {@link OidcTokenError} passes through **untouched** — not caught, not
+   * defaulted, not wrapped. Whether attestation is mandatory or best-effort
+   * is the consumer's policy: an action that must not publish unattested
+   * lets the error propagate, and one that publishes anyway catches it at
+   * its own boundary. `reason: "unavailable"` almost always means the
+   * workflow is missing `permissions: id-token: write`.
+   */
+  static readonly capture: (audience?: string) => Effect.Effect<SlsaProvenance, OidcTokenError, OidcTokenIssuer | ActionEnvironment>;
+}
+//#endregion
 //#region src/Artifact.d.ts
 declare const ArtifactError_base: Schema.Class<ArtifactError, Schema.TaggedStruct<"ArtifactError", {
   /**
@@ -1625,9 +2139,292 @@ declare class GitHubCacheBlobStore {
   static readonly layerWith: (transfer: DataBlobTransfer) => Layer.Layer<BlobStore, never, HttpClient.HttpClient | ActionEnvironment>;
 }
 //#endregion
-//#region src/DetachedProcess.d.ts
-declare const DetachedProcessError_base: Schema.Class<DetachedProcessError, Schema.TaggedStruct<"DetachedProcessError", {
-  /**
+//#region src/CheckDocument.d.ts
+declare const CheckReport_base: Schema.Class<CheckReport, Schema.Struct<{
+  /** Where the check is now. The last reported state is the authoritative one. */
+  readonly state: Schema.Literals<readonly ["running", "pass", "fail", "warn", "user_interaction_required", "skipped", "timeout"]>;
+  /** Display name, when it differs from the registry key. */
+  readonly title: Schema.optionalKey<Schema.String>;
+  /** A one-line verdict, e.g. `in progress...` or `3 packages ready`. */
+  readonly outcome: Schema.optionalKey<Schema.String>;
+  /** A pre-rendered markdown block of per-check detail. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** Where the check's name should link. */
+  readonly url: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * What a run knows about one of its checks: the authoritative state, and the
+ * presentation facts a renderer projects into the document.
+ *
+ * @remarks
+ * Only `state` is required. The rest exist because a status table needs them:
+ * `title` when the display name differs from the registry key, `outcome` for
+ * the one-line verdict cell, `url` for linking the check's name, and `detail`
+ * for the per-check block a body region carries. A later report for the same
+ * key **replaces** the whole entry — last write wins, per field and per check.
+ *
+ * @public
+ */
+declare class CheckReport extends CheckReport_base {}
+declare const CheckDocumentError_base: Schema.Class<CheckDocumentError, Schema.TaggedStruct<"CheckDocumentError", {
+  /** Which half failed: regenerating the document, or writing it. */
+  readonly kind: Schema.Literals<readonly ["render", "sink"]>;
+  /** The underlying failure. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the check document cannot be regenerated or written.
+ *
+ * @remarks
+ * `render` — projecting the registry onto the document failed, almost always
+ * because a reported `detail` contains a line the region scanner would read
+ * as a marker; the underlying `ManagedDocumentError` rides in `cause`.
+ * `sink` — the consumer's write effect failed; its error rides in `cause`.
+ * Callers of `flush` branch on `kind`; the background reconciler never fails
+ * a fiber with this — it logs and retries on the next report.
+ *
+ * @public
+ */
+declare class CheckDocumentError extends CheckDocumentError_base {
+  get message(): string;
+}
+/**
+ * How a rendered document leaves the process: the narrow sink contract.
+ *
+ * @remarks
+ * One rendered document in, one write effect out — nothing else. That is
+ * what lets the sticky PR comment (`PullRequestComment.upsert`), the PR
+ * description (`PATCH` on the pull request) and a test's recording `Ref` all
+ * fit the same reconciler. The success value is ignored; a failure surfaces
+ * as {@link CheckDocumentError} with `kind: "sink"`. Provide any services the
+ * write needs when constructing the sink — the reconciler runs it as given.
+ *
+ * @public
+ */
+type CheckDocumentSink = (rendered: string) => Effect.Effect<unknown, unknown>;
+/**
+ * Options for {@link CheckDocument.layer}.
+ *
+ * @public
+ */
+interface CheckDocumentOptions {
+  /** The managed document's namespace, e.g. your action's name. */
+  readonly namespace: string;
+  /** Which document, within that namespace. */
+  readonly key: string;
+  /**
+   * The document text to reconcile against initially — a PR body fetched
+   * once at startup, so human content outside the managed regions survives.
+   * Defaults to empty: a fresh document.
+   */
+  readonly initial?: string | undefined;
+  /**
+   * The pure projection from registry state to region entries.
+   *
+   * @remarks
+   * Called with the full snapshot on every reconcile pass; returns the
+   * regions to replace, keyed however the consumer's document is laid out —
+   * typically one region per check plus a shared status table. It must be a
+   * pure function of the snapshot: rendering the same state twice must
+   * produce the same entries, because byte-identical output is what
+   * suppresses the write.
+   */
+  readonly render: (checks: ReadonlyMap<string, CheckReport>) => ReadonlyArray<readonly [key: string, content: string]>;
+  /** Where the rendered document goes. */
+  readonly sink: CheckDocumentSink;
+  /**
+   * Debounce parameters: `quiet` is the trailing settle window, `maxWait`
+   * the staleness bound under a steady stream of reports. Defaults: 500
+   * milliseconds and 3 seconds.
+   */
+  readonly debounce?: {
+    readonly quiet?: Duration.Input | undefined;
+    readonly maxWait?: Duration.Input | undefined;
+  } | undefined;
+  /**
+   * How long one sink write may run before the pass fails with
+   * `kind: "sink"`. Default: 30 seconds.
+   *
+   * @remarks
+   * The reconciler serializes passes behind one permit, and the finalizer's
+   * last flush waits on that same permit — so a sink that never resolves
+   * would otherwise stall every later pass AND scope teardown. The bound
+   * turns a hung write into the ordinary sink failure path: a background
+   * pass logs and retries on the next report, `flush` surfaces the typed
+   * error.
+   */
+  readonly sinkTimeout?: Duration.Input | undefined;
+}
+/**
+ * The check-run → document reconciler's surface.
+ *
+ * @public
+ */
+interface CheckDocumentShape {
+  /**
+   * Record a check's current state and schedule a reconcile.
+   *
+   * @remarks
+   * Never fails and never blocks on the write — the state lands in the
+   * registry, and the debounced background pass projects it. Reporting the
+   * same key again replaces the entry; resolution is **not** terminal, so
+   * `pass` followed by `fail` leaves `fail` even inside one debounce window.
+   */
+  readonly report: (check: string, report: CheckReport) => Effect.Effect<void>;
+  /** The registry as of now, in first-report order. */
+  readonly checks: Effect.Effect<ReadonlyMap<string, CheckReport>>;
+  /**
+   * Reconcile immediately, skipping the debounce.
+   *
+   * @remarks
+   * Rendering unchanged state issues no write. Call it at the end of a run;
+   * the layer's finalizer also runs it, so the last burst of reports lands
+   * even when the scope closes inside the quiet window.
+   */
+  readonly flush: Effect.Effect<void, CheckDocumentError>;
+}
+declare const CheckDocument_base: Context.ServiceClass<CheckDocument, "@effected/github-actions/CheckDocument", CheckDocumentShape>;
+/**
+ * A living document of check state: an in-process registry the run reports
+ * into, debounced onto a marker-delimited document, written through a narrow
+ * sink.
+ *
+ * @remarks
+ * **Push, not pull.** The run owns its checks and knows when they resolve;
+ * nothing here polls GitHub. Consumers call `report` as states change, and a
+ * background fiber projects the registry onto a {@link ManagedDocument} —
+ * regions replaced from current state, so a check that resolves many times
+ * updates its region in place instead of appending.
+ *
+ * The debounce is **trailing with a max-wait, never leading**: a burst of
+ * reports coalesces into one write carrying the *final* state, and a steady
+ * stream still surfaces progress every `maxWait`. A pass that renders
+ * byte-identical text issues no write at all.
+ *
+ * `layer` mints fresh state per call — one layer per document. Bind it to a
+ * `const` if two parts of a program must share one registry.
+ *
+ * @example
+ * ```ts
+ * import { CheckDocument, CheckReport, GitHubMarkdown } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const layer = CheckDocument.layer({
+ *   namespace: "my-action",
+ *   key: "release-validation",
+ *   render: (checks) => [
+ *     [
+ *       "header",
+ *       GitHubMarkdown.table(
+ *         ["Check", "Outcome"],
+ *         [...checks].map(([key, check]) => [key, check.outcome ?? check.state]),
+ *       ),
+ *     ],
+ *   ],
+ *   sink: (rendered) => Effect.log(rendered),
+ * });
+ *
+ * const program = Effect.gen(function* () {
+ *   const doc = yield* CheckDocument;
+ *   yield* doc.report("build", CheckReport.make({ state: "running" }));
+ *   yield* doc.report("build", CheckReport.make({ state: "pass", outcome: "clean" }));
+ *   yield* doc.flush;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class CheckDocument extends CheckDocument_base {
+  /**
+   * The reconciler over one document.
+   *
+   * @remarks
+   * Forks the debounce fiber into the layer's scope and registers a
+   * finalizer that flushes once more on the way out, so the scope closing
+   * mid-window cannot strand the final state. A background pass that fails
+   * logs a structured warning and leaves the registry intact — the next
+   * report retries it; only `flush` surfaces the typed error.
+   */
+  static layer(options: CheckDocumentOptions): Layer.Layer<CheckDocument>;
+  /** An inert double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<CheckDocumentShape>) => CheckDocumentShape;
+  /** {@link CheckDocument.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<CheckDocumentShape>) => Layer.Layer<CheckDocument>;
+}
+//#endregion
+//#region src/CheckState.d.ts
+/**
+ * The kit's check-state vocabulary.
+ *
+ * @remarks
+ * Deliberately **wider than GitHub's own check-run conclusions**: `running` is
+ * a first-class state rather than the absence of a conclusion, and
+ * `user_interaction_required` names a release pipeline waiting on a human. A
+ * check's lifecycle is a *sequence* of these states, and only the last one is
+ * authoritative — resolution is not a terminal transition, so a check may run
+ * `running`, `pass`, `running`, `fail` in order, and that means `fail`.
+ *
+ * Every state projects onto GitHub's check-run wire vocabulary through
+ * {@link projectCheckState}. GitHub's `cancelled` conclusion has no
+ * counterpart here on purpose: cancellation is something the runner does *to*
+ * a run, not a state a pipeline reports about its own checks.
+ *
+ * @public
+ */
+declare const CheckState: Schema.Literals<readonly ["running", "pass", "fail", "warn", "user_interaction_required", "skipped", "timeout"]>;
+/**
+ * The type of `CheckState`.
+ *
+ * @public
+ */
+type CheckState = typeof CheckState.Type;
+/**
+ * The check-run conclusions the kit vocabulary can produce.
+ *
+ * @remarks
+ * A subset of GitHub's conclusion set, spelled structurally so a pure
+ * vocabulary module does not put `@effected/github` — and through it the
+ * octokit runtime — on its import graph. A structural assertion in the test
+ * suite pins these literals against `CheckConclusion` in `@effected/github`,
+ * so drift between the two spellings fails a test rather than a consumer.
+ *
+ * @public
+ */
+type CheckRunConclusion = "success" | "failure" | "neutral" | "skipped" | "timed_out" | "action_required";
+/**
+ * A `CheckState` on GitHub's check-run wire: a status, and a conclusion
+ * exactly when the status is `completed`.
+ *
+ * @remarks
+ * A discriminated union rather than two optional fields, because the wire
+ * protocol's own invariant is conditional: an in-progress check run *has* no
+ * conclusion, and a completed one always does.
+ *
+ * @public
+ */
+type CheckRunProjection = {
+  readonly status: "in_progress";
+} | {
+  readonly status: "completed";
+  readonly conclusion: CheckRunConclusion;
+};
+/**
+ * Project a kit check state onto GitHub's check-run wire vocabulary.
+ *
+ * @remarks
+ * The canonical mapping: `running` is `in_progress`; everything else is
+ * `completed` with `pass → success`, `fail → failure`, `warn → neutral`
+ * (GitHub has no warning conclusion, and `neutral` is its non-failing,
+ * non-success verdict), `user_interaction_required → action_required`,
+ * `skipped → skipped` and `timeout → timed_out`.
+ *
+ * @public
+ */
+declare const projectCheckState: (state: CheckState) => CheckRunProjection;
+//#endregion
+//#region src/DetachedProcess.d.ts
+declare const DetachedProcessError_base: Schema.Class<DetachedProcessError, Schema.TaggedStruct<"DetachedProcessError", {
+  /**
    * `logUnavailable` — the log file could not be opened, so there is nowhere
    * for the child's output to go. `spawnFailed` — the child did not start.
    * `invalidPid` — a non-positive pid was handed to {@link DetachedProcess.reap};
@@ -1896,6 +2693,230 @@ declare class DryRun extends DryRun_base {
   static readonly layerTest: (overrides?: Partial<DryRunShape>) => Layer.Layer<DryRun>;
 }
 //#endregion
+//#region src/GitHubMarkdown.d.ts
+/**
+ * A heading level GitHub renders, `1` through `6`.
+ *
+ * @public
+ */
+type GitHubHeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Options for {@link GitHubMarkdown.list}.
+ *
+ * @public
+ */
+interface GitHubListOptions {
+  /** Render `1.`-numbered items instead of bullets. */
+  readonly ordered?: boolean | undefined;
+}
+/**
+ * The row-schema constraint {@link GitHubMarkdown.tableFor} accepts: any
+ * schema exposing a struct field map — `Schema.Struct` and `Schema.Class`
+ * both qualify.
+ *
+ * @public
+ */
+type GitHubRowSchema = Schema.Constraint & {
+  readonly fields: Schema.Struct.Fields;
+};
+/**
+ * The field keys of a row schema whose column REQUIRES an explicit
+ * `format`: fields whose encoded side is not a string (their codec has no
+ * string projection to borrow), and fields whose encoding needs services
+ * (a sync cell render cannot provide them).
+ *
+ * @public
+ */
+type GitHubSchemaTableFormatRequiredKeys<Fields extends Schema.Struct.Fields> = { [K in keyof Fields]: [Fields[K]["Encoded"]] extends [string | undefined] ? [Fields[K]["EncodingServices"]] extends [never] ? never : K : K; }[keyof Fields];
+/**
+ * Per-column configuration for {@link GitHubMarkdown.tableFor}.
+ *
+ * @public
+ */
+interface GitHubSchemaTableColumn<Value> {
+  /**
+   * The column header, overriding the field schema's `title` annotation
+   * and the field-name fallback. Pre-rendered markdown, like every cell.
+   */
+  readonly header?: string | undefined;
+  /**
+   * Render a cell from the decoded field value instead of encoding it
+   * through the field's codec. Required — by type — for a field whose
+   * encoded side is not a string.
+   */
+  readonly format?: ((value: Value) => string) | undefined;
+}
+/**
+ * {@link GitHubSchemaTableColumn} with the `format` obligation discharged —
+ * the entry shape a non-string-encoded field demands.
+ *
+ * @public
+ */
+interface GitHubSchemaTableFormattedColumn<Value> extends GitHubSchemaTableColumn<Value> {
+  readonly format: (value: Value) => string;
+}
+/**
+ * The per-field column map for {@link GitHubMarkdown.tableFor}: entries are
+ * optional except where the field's encoded side is not a string, where the
+ * entry — and its `format` — are required.
+ *
+ * @public
+ */
+type GitHubSchemaTableColumns<Fields extends Schema.Struct.Fields> = { readonly [K in GitHubSchemaTableFormatRequiredKeys<Fields>]: GitHubSchemaTableFormattedColumn<Exclude<Fields[K]["Type"], undefined>>; } & { readonly [K in Exclude<keyof Fields, GitHubSchemaTableFormatRequiredKeys<Fields>>]?: GitHubSchemaTableColumn<Exclude<Fields[K]["Type"], undefined>>; };
+/**
+ * Options for {@link GitHubMarkdown.tableFor}. The whole bag is optional
+ * exactly when every field's encoded side is a string; one field without a
+ * string projection makes `columns` — and the entry carrying its `format` —
+ * required.
+ *
+ * @public
+ */
+type GitHubSchemaTableOptions<Fields extends Schema.Struct.Fields> = [GitHubSchemaTableFormatRequiredKeys<Fields>] extends [never] ? {
+  readonly columns?: GitHubSchemaTableColumns<Fields> | undefined;
+} : {
+  readonly columns: GitHubSchemaTableColumns<Fields>;
+};
+/**
+ * A renderer minted by {@link GitHubMarkdown.tableFor}: columns are fixed by
+ * the schema, rows are supplied at each render.
+ *
+ * @public
+ */
+interface GitHubSchemaTable<Row> {
+  /**
+   * Render the current rows as a GFM table. Pure and repeatable — identical
+   * rows produce identical output, so re-rendering from changed state is
+   * just calling it again.
+   */
+  render(rows: ReadonlyArray<Row>): string;
+}
+/**
+ * The fluent markdown writer for GitHub surfaces — PR comments, check-run
+ * summaries, job summaries.
+ *
+ * @remarks
+ * Every member takes **pre-rendered markdown** (links, emphasis, emoji — the
+ * caller's fragments pass through verbatim) and returns a `string`, so
+ * compositions read as plain string assembly. What the writer owns is the
+ * *structure*: wherever a fragment could break the construct around it, the
+ * output goes through `@effected/markdown`'s node classes and serializer
+ * rather than string joining. A table cell carrying `>=1 || <2` renders with
+ * its pipes escaped instead of shifting every column after it; a code block
+ * whose content contains a fence gets a longer fence; inline code containing
+ * a backtick gets a wider delimiter; a URL containing spaces or parentheses
+ * is angle-bracketed.
+ *
+ * This module is the package's **only** importer of `@effected/markdown` — a
+ * structural test pins that, on the same terms as the Azure confinement — so
+ * an action that never renders markdown never links the engine.
+ *
+ * @example
+ * ```ts
+ * import { GitHubMarkdown } from "@effected/github-actions";
+ *
+ * const body = [
+ *   GitHubMarkdown.heading("Release Validation"),
+ *   GitHubMarkdown.table(["Check", "Outcome"], [["build", "✅ passed"]]),
+ *   GitHubMarkdown.details("Logs", GitHubMarkdown.codeBlock(log, "text")),
+ * ].join("\n\n");
+ * ```
+ *
+ * @public
+ */
+declare class GitHubMarkdown {
+  private constructor();
+  /**
+   * A GFM table.
+   *
+   * @remarks
+   * Cells are pre-rendered markdown; the serializer escapes the pipes GFM
+   * would otherwise read as column breaks. Rows shorter than the header are
+   * padded with empty cells rather than shifting.
+   */
+  static table(headers: ReadonlyArray<string>, rows: ReadonlyArray<ReadonlyArray<string>>): string;
+  /**
+   * A GFM table whose columns are defined ONCE by a row schema.
+   *
+   * @remarks
+   * The schema is the single authority for the table's shape: column order
+   * is field declaration order, each header is the field's `title`
+   * annotation (fall back: the property name, overridable per column), and
+   * each cell is the field value's **encoded** string form — a branded or
+   * typed field projects through its own codec, so the vocabulary lives
+   * with the schema instead of being respelled at every call site, and a
+   * row can no longer transpose columns because it is a typed object, not
+   * a positional array.
+   *
+   * A field whose encoded side is not a string has no string projection to
+   * borrow; the type of `options` makes its column's `format` — and
+   * therefore `columns` and `options` themselves — required. An absent or
+   * `undefined` optional field renders as an empty cell without consulting
+   * codec or formatter.
+   *
+   * The renderer is a pure value: `render` maps current rows through
+   * {@link GitHubMarkdown.table}, so escaping is inherited and identical
+   * rows produce identical output. Rows are already-decoded values of the
+   * schema's type, so encoding them is total in practice; a value smuggled
+   * past the types throws the codec's `SchemaError` as a defect — same
+   * posture as the serializer arm above, **not** a silent fallback.
+   *
+   * Only string-keyed fields become columns; symbol keys are not
+   * enumerable table columns.
+   *
+   * @example
+   * ```ts
+   * import { GitHubMarkdown } from "@effected/github-actions";
+   * import { Schema } from "effect";
+   *
+   * const CheckRow = Schema.Struct({
+   *   name: Schema.String.annotate({ title: "Check" }),
+   *   outcome: Schema.Literals(["passed", "failed"]),
+   * });
+   * const checks = GitHubMarkdown.tableFor(CheckRow);
+   * const body = checks.render([{ name: "build", outcome: "passed" }]);
+   * ```
+   */
+  static tableFor<S extends GitHubRowSchema>(schema: S, ...options: [GitHubSchemaTableFormatRequiredKeys<S["fields"]>] extends [never] ? [options?: GitHubSchemaTableOptions<S["fields"]>] : [options: GitHubSchemaTableOptions<S["fields"]>]): GitHubSchemaTable<S["Type"]>;
+  /** An ATX heading; the level defaults to `2`. */
+  static heading(text: string, level?: GitHubHeadingDepth): string;
+  /** A link. URLs the destination cannot carry raw are angle-bracketed. */
+  static link(text: string, url: string): string;
+  /** Inline code. Content containing backticks widens the delimiter. */
+  static code(text: string): string;
+  /** A fenced code block. Content containing a fence lengthens the fence. */
+  static codeBlock(content: string, language?: string): string;
+  /**
+   * A list of pre-rendered markdown items.
+   *
+   * @remarks
+   * A multi-line item is indented onto continuation lines, so it stays part
+   * of its bullet instead of terminating the list.
+   */
+  static list(items: ReadonlyArray<string>, options?: GitHubListOptions): string;
+  /**
+   * A collapsible `<details>` block.
+   *
+   * @remarks
+   * mdast has no details node, so this is the one construct the writer emits
+   * as raw HTML. The blank lines around `body` are what make GitHub render
+   * the markdown inside it; `summary` is HTML context — markdown is **not**
+   * rendered there, so bold a summary with `<strong>`, not `**`.
+   */
+  static details(summary: string, body: string): string;
+  /**
+   * Pre-rendered markdown, passed through by name.
+   *
+   * @remarks
+   * The identity function, deliberately: every writer member already treats
+   * its fragments as markdown, so `raw` adds no behavior — it adds the
+   * *statement* that a value is already rendered. Use it where a fragment
+   * from elsewhere enters a composition and a reader would otherwise wonder
+   * whether it still needs escaping. It replaces the `Html.make` idiom,
+   * which passes markdown through correctly but announces the wrong intent.
+   */
+  static raw(markdown: string): string;
+}
+//#endregion
 //#region src/GitHubToken.d.ts
 declare const GitHubTokenError_base: Schema.Class<GitHubTokenError, Schema.TaggedStruct<"GitHubTokenError", {
   /**
@@ -2087,254 +3108,183 @@ declare class GitHubToken {
   static readonly dispose: (options?: ReadOptions | undefined) => Effect.Effect<void, ActionStateError | import("@effected/github").GitHubAppError, ActionState | GitHubApp>;
 }
 //#endregion
-//#region src/OidcTokenIssuer.d.ts
-declare const OidcTokenError_base: Schema.Class<OidcTokenError, Schema.TaggedStruct<"OidcTokenError", {
-  /**
-   * `unavailable` — the runner did not publish the token-service variables,
-   * which almost always means the workflow is missing `permissions: id-token:
-   * write`. `requestFailed` — the token service could not be reached or refused
-   * the request. `malformedResponse` — it answered with something that is not a
-   * token envelope. `malformedToken` — the token is not a decodable JWT.
-   * `missingClaims` — it decoded, but without the claims a provenance statement
-   * needs.
-   */
-  readonly reason: Schema.Literals<readonly ["unavailable", "requestFailed", "malformedResponse", "malformedToken", "missingClaims"]>;
-  /** What was wrong, in one line. */
-  readonly detail: Schema.optionalKey<Schema.String>;
-  /** The HTTP status, when the token service answered. */
-  readonly status: Schema.optionalKey<Schema.Number>;
-  /** The underlying failure, preserved structurally. */
-  readonly cause: Schema.optionalKey<Schema.Defect>;
+//#region src/ManagedDocument.d.ts
+declare const ManagedDocumentError_base: Schema.Class<ManagedDocumentError, Schema.TaggedStruct<"ManagedDocumentError", {
+  /** Which ambiguity or refusal was found. */
+  readonly kind: Schema.Literals<readonly ["unterminatedRegion", "orphanedEnd", "overlappingRegions", "duplicateRegion", "markerInContent", "duplicateDeclaration"]>;
+  /** 1-based line of the offending marker, for the structural kinds. */
+  readonly line: Schema.optionalKey<Schema.Number>;
+  /** The region key involved, when the failure names one. */
+  readonly key: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Raised when an OIDC token cannot be issued or read.
+ * Raised when a managed document cannot be read or regenerated without
+ * guessing.
+ *
+ * @remarks
+ * The four structural kinds (`unterminatedRegion`, `orphanedEnd`,
+ * `overlappingRegions`, `duplicateRegion`) surface at parse time and name an
+ * ambiguity whose silent resolution would corrupt content a human wrote by
+ * hand. The two declaration kinds surface when regions are applied:
+ * `markerInContent` refuses region content that itself contains a line the
+ * scanner would read as a region marker, and `duplicateDeclaration` refuses
+ * one call that states two intentions for the same region.
  *
  * @public
  */
-declare class OidcTokenError extends OidcTokenError_base {
+declare class ManagedDocumentError extends ManagedDocumentError_base {
   get message(): string;
 }
-declare const OidcClaims_base: Schema.Class<OidcClaims, Schema.Struct<{
-  /** The issuer, e.g. `https://token.actions.githubusercontent.com`. */
-  readonly iss: Schema.String;
-  /** The full ref the workflow ran on. */
-  readonly ref: Schema.String;
-  /** The commit. */
-  readonly sha: Schema.String;
-  /** `owner/repo`. */
-  readonly repository: Schema.String;
-  /** The event that triggered the run. */
-  readonly event_name: Schema.String;
-  /** The reusable-workflow ref, which is what a verifier pins against. */
-  readonly job_workflow_ref: Schema.String;
-  /** The calling workflow's ref. */
-  readonly workflow_ref: Schema.String;
-  /** The numeric repository id, as a string. */
-  readonly repository_id: Schema.String;
-  /** The numeric owner id, as a string. */
-  readonly repository_owner_id: Schema.String;
-  /** `github-hosted` or `self-hosted`. */
-  readonly runner_environment: Schema.String;
-  /** The run id, as a string. */
-  readonly run_id: Schema.String;
-  /** The run attempt, as a string. */
-  readonly run_attempt: Schema.String;
-}>, {}>;
 /**
- * The claims a GitHub Actions OIDC token carries about the workflow that ran.
- *
- * @remarks
- * The field names are GitHub's own JWT claim names, kept verbatim rather than
- * translated to the kit's casing. They are an **external vocabulary** — the
- * same strings that appear in a SLSA provenance predicate and in every
- * published example of an Actions OIDC policy — and renaming them would put a
- * translation layer between a consumer and the specification they are reading.
+ * Options identifying a managed document inside a text that may not carry one
+ * yet.
  *
  * @public
  */
-declare class OidcClaims extends OidcClaims_base {}
-/**
- * The {@link OidcTokenIssuer} service shape.
- *
- * @public
- */
-interface OidcTokenIssuerShape {
+interface ManagedDocumentSource {
+  /** Whose document this is, e.g. your action's name. */
+  readonly namespace: string;
+  /** Which document, within that namespace. */
+  readonly key: string;
   /**
-   * Request an ID token, optionally bound to an audience.
-   *
-   * @remarks
-   * Omitting the audience sends no `audience` parameter at all, matching
-   * `@actions/core.getIDToken` — the runner's default audience is not the empty
-   * string.
+   * The current text — a fetched comment body, a PR description — or absent
+   * when there is nothing yet. An absent text and an empty one mean the same
+   * thing: a fresh document.
    */
-  readonly token: (audience?: string) => Effect.Effect<Redacted.Redacted<string>, OidcTokenError>;
-  /**
-   * The token's claims, decoded.
-   *
-   * @remarks
-   * **The signature is deliberately not verified**, for three reasons that are
-   * recorded so nobody "fixes" it:
-   *
-   * 1. The token comes from the runner's own token-service endpoint over TLS.
-   *    The transport is the trust boundary, and the process asking for the
-   *    token is the process that received it.
-   * 2. The claims populate a provenance predicate, not a trust decision.
-   *    Nothing branches on them for authorization; they are recorded as
-   *    attested facts about the workflow that ran.
-   * 3. Verifying would need a JWKS fetch, which turns a decode into a network
-   *    call — untestable without a fixture server, and dependent on GitHub's
-   *    key endpoint being reachable at attestation time.
-   *
-   * A consumer that needs a *verified* token needs a different operation with a
-   * different name and a different error channel, not an option on this one.
-   *
-   * Claims are on the surface rather than left to the call site because that is
-   * what makes the provenance path reachable in a test: a double built with
-   * {@link OidcTokenIssuer.layerFor} answers with real, decodable claims, where
-   * the synthetic non-JWT its predecessor returned made every consumer's
-   * `decodeJwtClaims` yield nothing and silently skipped the path under test.
-   */
-  readonly claims: (audience?: string) => Effect.Effect<OidcClaims, OidcTokenError>;
+  readonly text?: string | undefined;
 }
-declare const OidcTokenIssuer_base: Context.ServiceClass<OidcTokenIssuer, "@effected/github-actions/OidcTokenIssuer", OidcTokenIssuerShape>;
+declare const ManagedDocument_base: Schema.Class<ManagedDocument, Schema.Struct<{
+  /** Whose document this is. */
+  readonly namespace: Schema.String;
+  /** Which document, within that namespace. */
+  readonly key: Schema.String;
+  /** The document's full text, sentinel and regions included. */
+  readonly text: Schema.String;
+}>, {}>;
 /**
- * The runner's OIDC token service.
+ * A marker-delimited document: named regions a tool owns, inside text a human
+ * may also edit.
  *
  * @remarks
- * Lives here rather than with attestation because it reads
- * `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL`, which
- * exist only when a workflow declares `permissions: id-token: write` — that is
- * a fact about the runner, not about signing.
+ * The one primitive behind both the sticky PR comment and the managed PR
+ * description. A sentinel HTML comment (`<!-- namespace:key -->`) identifies
+ * the document; each region is delimited by HTML-comment markers keyed
+ * `namespace.key.region`; and everything outside the managed regions is
+ * preserved byte-for-byte on regeneration. Regions are **replaced from
+ * current state, never appended** — applying the same region twice yields one
+ * region carrying the latest content, which is what makes a check that
+ * resolves many times safe to re-render.
+ *
+ * The region engine is `@effected/templates`' pure `SectionDocument` —
+ * reused, not reinvented — fixed to the HTML comment style and a
+ * region-specific phrase. Everything here is string → string; the GitHub
+ * write path composes this with `PullRequestComment` (whose `CommentMarker`
+ * renders the *same* sentinel for the same namespace and key) or a PR-body
+ * update in `@effected/github`.
+ *
+ * Construct with {@link ManagedDocument.parseResult} — create-or-update in
+ * one call, so the consumer never branches on whether the document exists
+ * yet. `ManagedDocument.make` is the raw schema constructor and performs no
+ * structural validation.
  *
  * @example
  * ```ts
- * import { OidcTokenIssuer } from "@effected/github-actions";
- * import { Effect } from "effect";
- *
- * const program = Effect.gen(function* () {
- *   const issuer = yield* OidcTokenIssuer;
- *   const claims = yield* issuer.claims("sigstore");
- *   return claims.job_workflow_ref;
- * });
+ * import { ManagedDocument } from "@effected/github-actions";
+ * import { Result } from "effect";
+ *
+ * const doc = ManagedDocument.parseResult({ namespace: "my-action", key: "release", text: fetched });
+ * if (Result.isSuccess(doc)) {
+ *   const next = doc.success.withRegionsResult([
+ *     ["header", "## Validating Release"],
+ *     ["footer", "generated by my-action"],
+ *   ]);
+ * }
  * ```
  *
  * @public
  */
-declare class OidcTokenIssuer extends OidcTokenIssuer_base {
-  static readonly layer: Layer.Layer<OidcTokenIssuer, never, ActionEnvironment | HttpClient.HttpClient>;
+declare class ManagedDocument extends ManagedDocument_base {
   /**
-   * An **unsigned** JWT carrying these claims.
+   * Read a document out of existing text, or begin a fresh one.
    *
    * @remarks
-   * For building test doubles, and nothing else: the signature segment is a
-   * placeholder, so this token would fail any verifier. It exists because the
-   * alternative — a double returning a synthetic non-JWT — is what made the
-   * provenance path structurally unreachable in the source package, drawing
-   * four separate apologetic comments from one consumer.
+   * The synchronous primitive; {@link ManagedDocument.parse} derives from it.
+   * Absent text, empty text and text that carries no sentinel are all legal —
+   * the sentinel and regions are added by the first
+   * {@link ManagedDocument.withRegionsResult}. Only a *structurally corrupt*
+   * region layout fails, because every structural ambiguity is a case where
+   * a silent choice would destroy content a human wrote.
    */
-  static readonly unsignedTokenFor: (claims: OidcClaims) => Redacted.Redacted<string>;
-  /** A test double. Unstubbed members die rather than answering with a non-token. */
-  static readonly makeTest: (overrides?: Partial<OidcTokenIssuerShape>) => OidcTokenIssuerShape;
-  /** {@link OidcTokenIssuer.makeTest} behind `Layer.succeed`. */
-  static readonly layerTest: (overrides?: Partial<OidcTokenIssuerShape>) => Layer.Layer<OidcTokenIssuer>;
+  static parseResult(source: ManagedDocumentSource): Result.Result<ManagedDocument, ManagedDocumentError>;
   /**
-   * A double that answers with these claims, consistently on both members.
+   * Read a document out of existing text, in `Effect`.
    *
    * @remarks
-   * `token()` returns a real decodable JWT built from the same claims
-   * `claims()` returns, so a consumer that decodes the token itself and a
-   * consumer that asks the service both see the same thing. A double whose two
-   * members can disagree is how a test proves a path works while production
-   * takes the other one.
+   * Defined in terms of {@link ManagedDocument.parseResult} — synchronous
+   * callers can use that variant directly.
    */
-  static readonly layerFor: (claims: OidcClaims) => Layer.Layer<OidcTokenIssuer>;
-}
-//#endregion
-//#region src/Secret.d.ts
-/**
- * The declassification seam: the **only** place in this package where a
- * `Redacted` value becomes a plain string.
- *
- * @remarks
- * Some boundaries cannot carry a `Redacted`. A detached child process reads
- * its configuration from environment variables; `GITHUB_STATE` is a plaintext
- * file by GitHub's protocol. `Redacted` refusing to serialize is the whole
- * value of the type, so this module does not try to make it serializable —
- * it makes declassification **explicit, auditable, and impossible to do
- * quietly**.
- *
- * The invariant: **masking and declassification are the same call.** Every
- * member registers the value with the runner's log filter (`::add-mask::`)
- * *before* returning plaintext, so a secret cannot reach a child's environment
- * or a state file without the runner already knowing to redact it from logs.
- *
- * `Redacted.value` appears nowhere else in this package, and a test asserts
- * that structurally — a reintroduction elsewhere fails the suite rather than
- * review.
- *
- * What this deliberately does **not** do is encrypt the handoff. The child
- * runs on the same runner, as the same user, as the parent; a key would have
- * to travel the same channel as the secret it protects.
- *
- * @example
- * ```ts
- * import { Secret } from "@effected/github-actions";
- * import { Effect } from "effect";
- *
- * const program = Effect.gen(function* () {
- *   const env = yield* Secret.forChildEnv({ MY_TOKEN: theToken });
- *   // every value in `env` is already masked in the runner log
- *   return env;
- * });
- * ```
- *
- * @public
- */
-declare class Secret {
-  private constructor();
+  static readonly parse: (source: ManagedDocumentSource) => Effect.Effect<ManagedDocument, ManagedDocumentError, never>;
+  /** The HTML comment identifying this document, `<!-- namespace:key -->`. */
+  get sentinel(): string;
+  /** Does this text carry the document's sentinel? */
+  matches(text: string): boolean;
+  /** The content of one region, if the document carries it. */
+  region(key: string): Option.Option<string>;
+  /** Every region this document carries, in document order. */
+  get regions(): ReadonlyArray<{
+    readonly key: string;
+    readonly content: string;
+  }>;
   /**
-   * Declassify a set of secrets for a child process's environment.
+   * The document with these regions replaced from current state.
    *
    * @remarks
-   * Every value is masked before any plaintext is returned — including when
-   * one of them fails, because masking happens for the whole set first.
+   * The synchronous primitive; {@link ManagedDocument.withRegions} derives
+   * from it. Each entry pairs a region key with its full new content. A
+   * region already present is **replaced in place**; a region not present
+   * yet is added; regions not named are left exactly as they are; and every
+   * byte outside a managed region survives untouched. Applying entries that
+   * change nothing returns byte-identical text, which is what lets a caller
+   * compare-and-skip instead of issuing a write.
+   *
+   * Region keys share the name grammar `namespace` and `key` obey; a key
+   * outside it is a wiring error and throws at construction rather than
+   * surfacing in the typed channel.
    */
-  static readonly forChildEnv: (entries: Readonly<Record<string, Redacted.Redacted<string>>>) => Effect.Effect<Record<string, string>, never, ActionOutputs>;
+  withRegionsResult(entries: ReadonlyArray<readonly [key: string, content: string]>): Result.Result<ManagedDocument, ManagedDocumentError>;
   /**
-   * Declassify one secret for a runner file (`GITHUB_STATE`, `GITHUB_OUTPUT`).
+   * The document with these regions replaced, in `Effect`.
    *
    * @remarks
-   * Masks first. The runner file is plaintext regardless; the mask is what
-   * keeps the value out of the visible log.
+   * Defined in terms of {@link ManagedDocument.withRegionsResult} —
+   * synchronous callers can use that variant directly.
    */
-  static readonly forRunnerFile: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
+  withRegions(entries: ReadonlyArray<readonly [key: string, content: string]>): Effect.Effect<ManagedDocument, ManagedDocumentError>;
+  /** The marker key a region is written under: `namespace.key.region`. */
+  private wireKey;
+  /** The region key back out of a wire key, for error reporting. */
+  private regionKeyOf;
   /**
-   * Declassify one secret for an in-process use that needs the raw bytes.
+   * This document's own regions, in document order.
    *
    * @remarks
-   * Request signing is the case this exists for: an HMAC cannot be computed
-   * over a `Redacted`, so a signing key has to become a string somewhere, and
-   * the point of this module is that "somewhere" is here and nowhere else.
-   *
-   * It masks even though the value is never *written* anywhere, and that is
-   * deliberate rather than superstitious: a signing key that leaks does so
-   * through something nobody audited — a debug log of outgoing headers, a
-   * serialized error, a stack trace carrying the closure. Registering it with
-   * the runner's filter costs one call and makes every one of those redacted.
-   *
-   * Call it **once, at layer construction**, not per operation: masking is
-   * idempotent but a workflow command per request is noise in the log.
+   * A document a human already edited can be structurally corrupt, and a
+   * read has no error channel worth having — a corrupt document simply has
+   * no readable regions; {@link ManagedDocument.parseResult} is where
+   * corruption fails typed. Regions belonging to a *different* document in
+   * the same text (another namespace or key) are not this document's and are
+   * never reported.
    */
-  static readonly forSigning: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
+  private ownRegions;
   /**
-   * The far side of a handoff: re-wrap a plaintext environment variable.
+   * Append the sentinel when the text does not carry it yet.
    *
    * @remarks
-   * A `Config`, so a missing or empty handoff is an honest `ConfigError`
-   * naming the variable rather than an empty `Redacted` that fails much later
-   * as an authentication error.
+   * Appended at the end — the same position `PullRequestComment.upsert`
+   * writes its marker to — so a document rendered here and a comment written
+   * there agree about where the identity line lives.
    */
-  static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
+  private ensureSentinel;
 }
 //#endregion
 //#region src/ToolInstaller.d.ts
@@ -2380,9 +3330,75 @@ declare class ToolInstallerError extends ToolInstallerError_base {
 interface ExtractOptions {
   /** The destination. A fresh temporary directory when omitted. */
   readonly destination?: string | undefined;
-  /** Flags for `tar`. Defaults to `["xzf"]`, i.e. a gzipped tarball. */
+  /**
+   * Flags for `tar`. Defaults to `["xzf"]`, i.e. a gzipped tarball.
+   *
+   * @remarks
+   * The argv is assembled as `[...flags, archive, "-C", destination]` — the
+   * archive path is appended directly AFTER the flags, so the LAST flag must
+   * be the one that consumes the archive operand. `["xzf"]` works because `f`
+   * is last inside the cluster; a custom set like `["xz", "--strip=1", "-f"]`
+   * must end the same way, deliberately rather than by ordering luck.
+   */
   readonly flags?: ReadonlyArray<string> | undefined;
 }
+/**
+ * How a {@link ToolInstallerShape.download} should behave.
+ *
+ * @public
+ */
+interface ToolDownloadOptions {
+  /**
+   * The overall time budget for ONE download attempt (request plus streaming
+   * the body to disk). Defaults to five minutes.
+   *
+   * @remarks
+   * The default is deliberately generous: toolchain archives run to hundreds
+   * of megabytes, and a healthy runner connection moves tens of megabytes a
+   * second — even a 500 MB archive on a degraded 2 MB/s link fits in five
+   * minutes. What the budget exists for is the connection that stops moving
+   * entirely: without it, a dead connection is a silent CI hang until the job
+   * timeout; with it, the attempt fails typed as `downloadFailed` with no
+   * status — which `retryable` classifies as a transport fault — and the
+   * download's own retry policy tries again.
+   */
+  readonly timeout?: Duration.Input | undefined;
+}
+/**
+ * What {@link ToolInstallerShape.provisionFile} should provision.
+ *
+ * @public
+ */
+interface ProvisionFileOptions {
+  /** The tool-cache name the binary is provisioned under, e.g. `"biome"`. */
+  readonly tool: string;
+  /** The exact version — a tool-cache path segment, so spell it canonically. */
+  readonly version: string;
+  /** The url the binary downloads from on a cache miss. */
+  readonly url: string;
+  /**
+   * The cached file's name — what the tool is invoked as once its directory
+   * is on the `PATH` (e.g. `"biome"`, or `"biome.exe"` on Windows).
+   */
+  readonly binary: string;
+}
+/**
+ * Where {@link ToolInstallerShape.provisionFile} put a single-binary tool.
+ *
+ * @remarks
+ * The same `directory`/`binDir` shape as `PackageManagerInstaller`'s
+ * `CachedPackageManager`, so a consumer publishes either the same way. For a
+ * single binary the two coincide: the cached directory contains exactly the
+ * executable, so it IS the directory to hand to `ActionOutputs.addPath`.
+ *
+ * @public
+ */
+interface ProvisionedFile {
+  /** The cached entry: `<tool-cache>/<tool>/<version>/<arch>`. */
+  readonly directory: string;
+  /** The directory to `addPath` — for a single binary, the cached directory itself. */
+  readonly binDir: string;
+}
 /**
  * The {@link ToolInstaller} service shape.
  *
@@ -2395,10 +3411,20 @@ interface ToolInstallerShape {
    * @remarks
    * Absent is not an error, and neither is an unreadable cache: both mean
    * "install it", which is the only thing a caller can do about either.
+   *
+   * **The tool cache is SHARED.** The hosted runner image pre-populates it and
+   * every `setup-*` action writes into it — this package is a co-writer, not
+   * the owner. A hit guarantees only the `<root>/<tool>/<version>/<arch>`
+   * location contract ({@link ToolInstaller.cachePath}); the directory's
+   * *interior* layout is whatever its writer produced, which is not
+   * necessarily what this consumer's own `cacheDir` would have written.
+   * Validate the layout of a foreign hit before relying on it — applying an
+   * assumption from your own install path (an archive-wrapper subdirectory,
+   * say) to a foreign entry is a real shipped bug.
    */
   readonly find: (tool: string, version: string) => Effect.Effect<Option.Option<string>>;
   /** Download a url to a temporary file, retrying what is worth retrying. */
-  readonly download: (url: string) => Effect.Effect<string, ToolInstallerError>;
+  readonly download: (url: string, options?: ToolDownloadOptions) => Effect.Effect<string, ToolInstallerError>;
   /** Extract a tarball. Returns the directory its contents landed in. */
   readonly extractTar: (archive: string, options?: ExtractOptions) => Effect.Effect<string, ToolInstallerError>;
   /** Extract a zip. Returns the directory its contents landed in. */
@@ -2407,16 +3433,38 @@ interface ToolInstallerShape {
   readonly cacheDir: (source: string, tool: string, version: string) => Effect.Effect<string, ToolInstallerError>;
   /** Install a single file into the tool cache under `name`. Returns the cached directory. */
   readonly cacheFile: (source: string, name: string, tool: string, version: string) => Effect.Effect<string, ToolInstallerError>;
+  /**
+   * Provision a single-binary tool: the whole `find` → `download` →
+   * chmod → `cacheFile` composition as one call.
+   *
+   * @remarks
+   * The one packaged workflow among the primitives, because the single-binary
+   * shape (biome, and every Rust/Go tool distributed as a bare executable) has
+   * no per-tool variation left to compose: there is no archive, so no
+   * extraction and no layout fixup. A cache hit whose entry contains the
+   * named `binary` short-circuits; a hit *missing* it — a foreign or partial
+   * entry, see {@link ToolInstallerShape.find}'s shared-cache warning — is
+   * treated as a miss and reinstalled over, rather than handing back a
+   * directory that cannot run the tool. On the install path the downloaded
+   * file is made executable (`0o755`) BEFORE caching — skipped when
+   * `RUNNER_OS` is Windows, where the bit does not exist — so the cache only
+   * ever contains a runnable tool; a chmod failure is `cacheFailed` with the
+   * file as its subject.
+   */
+  readonly provisionFile: (options: ProvisionFileOptions) => Effect.Effect<ProvisionedFile, ToolInstallerError>;
 }
 declare const ToolInstaller_base: Context.ServiceClass<ToolInstaller, "@effected/github-actions/ToolInstaller", ToolInstallerShape>;
 /**
  * Download, extract and cache a toolchain in the runner's tool cache.
  *
  * @remarks
- * The primitives, not a workflow: a consumer composes `find` → `download` →
- * `extractTar` → `cacheDir` in whatever order its tool needs, because the
- * orders genuinely differ (a single binary skips extraction, a tarball with a
- * nested root directory needs a path fixup between extract and cache).
+ * The primitives, plus exactly one packaged workflow: a consumer composes
+ * `find` → `download` → `extractTar` → `cacheDir` in whatever order its tool
+ * needs, because the orders genuinely differ (a tarball with a nested root
+ * directory needs a path fixup between extract and cache). The one shape with
+ * no per-tool variation — a single bare binary, which skips extraction and
+ * needs only the executable bit — ships whole as
+ * {@link ToolInstallerShape.provisionFile}.
  *
  * No `@actions/tool-cache` dependency — the cache is a directory layout, and
  * this reproduces the layout rather than importing a package to compute it.
@@ -2463,5 +3511,339 @@ declare class ToolInstaller extends ToolInstaller_base {
   static readonly layerTest: (overrides?: Partial<ToolInstallerShape>) => Layer.Layer<ToolInstaller>;
 }
 //#endregion
-export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, GitHubToken, GitHubTokenError, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, ProcessId, type ProvisionOptions, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, WorkflowCommand, describeCause };
+//#region src/PackageManagerInstaller.d.ts
+declare const PackageManagerInstallerError_base: Schema.Class<PackageManagerInstallerError, Schema.TaggedStruct<"PackageManagerInstallerError", {
+  /**
+   * `downloadFailed`, `extractFailed` and `cacheFailed` mirror the
+   * {@link ToolInstallerError} that caused them, preserved on `cause`
+   * (`cacheFailed` also covers a shim that could not be written into the
+   * entry). `integrityMismatch` — the downloaded artifact does not hash to
+   * what the pin declares; nothing was cached. `integrityMissing` — the pin
+   * carries no integrity and the caller asked for `requireIntegrity`.
+   * `unsupportedPlatform` — bun publishes no build for this runner's
+   * OS/architecture pair. `layoutUnexpected` — the artifact extracted, but
+   * its contents are not shaped like the package manager it claims to be.
+   */
+  readonly reason: Schema.Literals<readonly ["downloadFailed", "extractFailed", "integrityMismatch", "integrityMissing", "unsupportedPlatform", "layoutUnexpected", "cacheFailed"]>;
+  /** The package manager being installed. */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The exact version being installed, in string form. */
+  readonly version: Schema.String;
+  /** What was being worked on — a url, a path, or an OS/arch pair. */
+  readonly subject: Schema.optionalKey<Schema.String>;
+  /** The integrity the pin declares (`<algo>.<hex>`), on a mismatch. */
+  readonly expected: Schema.optionalKey<Schema.String>;
+  /** The integrity the artifact actually hashed to, on a mismatch. */
+  readonly actual: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a package manager cannot be provisioned on the runner.
+ *
+ * @public
+ */
+declare class PackageManagerInstallerError extends PackageManagerInstallerError_base {
+  get message(): string;
+}
+/**
+ * How {@link PackageManagerInstallerShape.install} should behave.
+ *
+ * @public
+ */
+interface PackageManagerInstallOptions {
+  /**
+   * Fail with `integrityMissing` when the pin carries no integrity hash,
+   * instead of proceeding with a logged warning. Off by default, because
+   * in-the-wild `devEngines` pins routinely carry no integrity.
+   */
+  readonly requireIntegrity?: boolean | undefined;
+  /**
+   * The npm registry host the npm, pnpm and yarn tarballs download from.
+   * Defaults to `https://registry.npmjs.org`; a corporate mirror that serves
+   * the standard `/<name>/-/<basename>-<version>.tgz` tarball routes works
+   * unchanged. bun does not ship through a registry — its per-platform zip
+   * always comes from GitHub releases.
+   */
+  readonly registry?: string | undefined;
+  /**
+   * Whether an npm pin may be answered by the runner's own ambient npm.
+   * Defaults to `true`.
+   *
+   * @remarks
+   * Set `false` when the run REPLACES node: a consumer that installs a pinned
+   * node in the same run puts that node's bundled npm ahead of the runner's on
+   * every path that matters afterward (the install child's `PATH`, and every
+   * later workflow step via `GITHUB_PATH`). The ambient probe interrogates the
+   * RUNNER's npm, so its exact-version match can diverge from the npm that
+   * actually executes once the pinned node shadows it. Suppressing the probe
+   * skips it entirely — no `npm --version` is ever spawned — and the install
+   * goes straight to the tool-cache/dist path, answering
+   * `source: "tool-cache"` with its own `binDir` as usual.
+   */
+  readonly allowAmbient?: boolean | undefined;
+}
+declare const AmbientPackageManager_base: Schema.Class<AmbientPackageManager, Schema.Struct<{
+  /** The discriminant: the runner's own toolchain answered. */
+  readonly source: Schema.tag<"ambient">;
+  /** The package-manager name (`npm`, `pnpm`, `yarn` or `bun`). */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The exact installed version, in string form. */
+  readonly version: Schema.String;
+  /** Bin name → the ambient command name that invokes it. */
+  readonly bins: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A package manager the runner's own toolchain already had: nothing was
+ * downloaded and nothing was cached, so there is no directory to publish.
+ *
+ * @remarks
+ * `bins` values are bare command names (`npm`, `npx`) resolved through the
+ * ambient `PATH` — the toolchain already put them there.
+ *
+ * @public
+ */
+declare class AmbientPackageManager extends AmbientPackageManager_base {}
+declare const CachedPackageManager_base: Schema.Class<CachedPackageManager, Schema.Struct<{
+  /** The discriminant: the manager lives in the tool cache. */
+  readonly source: Schema.tag<"tool-cache">;
+  /** The package-manager name (`npm`, `pnpm`, `yarn` or `bun`). */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The exact installed version, in string form. */
+  readonly version: Schema.String;
+  /** The cached entry: `<tool-cache>/<name>/<version>/<arch>`. */
+  readonly directory: Schema.String;
+  /** The directory to `addPath` — executable shims, or bun's own directory. */
+  readonly binDir: Schema.String;
+  /** Bin name → the absolute path of the underlying entry point. */
+  readonly bins: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A package manager living in the runner's tool cache — found there, or
+ * installed into it by this call.
+ *
+ * @remarks
+ * `binDir` is the directory a consumer hands to `ActionOutputs.addPath` to
+ * make the manager invokable by name in subsequent workflow steps. For the
+ * npm-registry managers it is the entry's `.bin` directory of executable
+ * shims this installer writes (`#!/bin/sh` exec wrappers, or `.cmd` wrappers
+ * on Windows); for bun it is the entry directory itself, because the cached
+ * `bun` binary is directly executable and a shim would add nothing but a
+ * fork. `bins` still maps each published bin name to the underlying entry —
+ * a Node script to run with `node` for npm/pnpm/yarn, the native binary for
+ * bun. Calling `addPath` remains deliberately the consumer's move, and note
+ * that `addPath` targets *subsequent* steps: a same-process probe must use
+ * the absolute paths in `bins` or `binDir`.
+ *
+ * @public
+ */
+declare class CachedPackageManager extends CachedPackageManager_base {}
+/**
+ * An installed package manager, discriminated by `source`: `ambient` carries
+ * no directory, `tool-cache` carries the cached `directory` and the
+ * `addPath`-able `binDir`. The union is a `Schema`, so the record round-trips
+ * through `ActionState` for a later phase to read back.
+ *
+ * @remarks
+ * **Construct the variant classes, never the union.** The union's inherited
+ * `make` typechecks against *both* variants at once, so a wrong field yields
+ * a confusing two-branch error instead of "this variant wants X" — reach for
+ * {@link AmbientPackageManager}`.make` / {@link CachedPackageManager}`.make`,
+ * whose `Schema.tag` fills `source` for you. The same tag is why an
+ * overrides-style test helper should be typed
+ * `Partial<Omit<typeof CachedPackageManager.Type, "source">>` — a plain
+ * `Partial` offers `source`, which `make` auto-fills and rejects as input.
+ *
+ * @public
+ */
+declare const InstalledPackageManager: Schema.Union<readonly [typeof AmbientPackageManager, typeof CachedPackageManager]>;
+/**
+ * The decoded type of {@link (InstalledPackageManager:variable)}:
+ * {@link AmbientPackageManager} `|` {@link CachedPackageManager}.
+ *
+ * @public
+ */
+type InstalledPackageManager = typeof InstalledPackageManager.Type;
+/**
+ * The {@link PackageManagerInstaller} service shape.
+ *
+ * @public
+ */
+interface PackageManagerInstallerShape {
+  /**
+   * Provision the exact package-manager version a pin names, answering with
+   * where it landed and how to invoke it.
+   */
+  readonly install: (pin: PackageManagerPin, options?: PackageManagerInstallOptions) => Effect.Effect<InstalledPackageManager, PackageManagerInstallerError>;
+}
+declare const PackageManagerInstaller_base: Context.ServiceClass<PackageManagerInstaller, "@effected/github-actions/PackageManagerInstaller", PackageManagerInstallerShape>;
+/**
+ * First-class exact-version package-manager provisioning on a GitHub runner.
+ *
+ * @remarks
+ * Takes a corepack pin (`@effected/npm`'s `PackageManagerPin`) and answers
+ * with an installed manager: tool-cache `find` first, then — for npm — an
+ * ambient `npm --version` probe (every Node toolchain ships npm), and only
+ * then the manager's own dist: npm, pnpm and yarn 1.x from their registry
+ * tarballs, yarn 2+ (Berry) from `@yarnpkg/cli-dist`, bun from its
+ * per-platform GitHub-release zip. A pin that carries integrity is verified
+ * fail-closed against what corepack itself hashes; one that does not proceeds
+ * with a logged warning unless `requireIntegrity` says otherwise.
+ *
+ * Every tool-cache answer carries a `binDir` a consumer can hand straight to
+ * `ActionOutputs.addPath`: the npm-registry managers get a `.bin` directory
+ * of executable shims written as part of the cached entry, bun's entry is its
+ * own `binDir`. Caching goes through {@link ToolInstaller}, so the
+ * stage-then-swap invariant holds here for free — shims included, the tool
+ * cache only ever contains complete package managers.
+ *
+ * @example
+ * ```ts
+ * import { ActionOutputs, PackageManagerInstaller } from "@effected/github-actions";
+ * import { PackageManagerPin } from "@effected/npm";
+ * import { Effect } from "effect";
+ *
+ * const provision = Effect.gen(function* () {
+ *   const installer = yield* PackageManagerInstaller;
+ *   const outputs = yield* ActionOutputs;
+ *   const pin = yield* PackageManagerPin.parse("pnpm@10.13.1");
+ *   const installed = yield* installer.install(pin);
+ *   if (installed.source === "tool-cache") {
+ *     yield* outputs.addPath(installed.binDir);
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class PackageManagerInstaller extends PackageManagerInstaller_base {
+  static readonly layer: Layer.Layer<PackageManagerInstaller, never, ActionEnvironment | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner | ToolInstaller>;
+  /** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
+  static readonly makeTest: (overrides?: Partial<PackageManagerInstallerShape>) => PackageManagerInstallerShape;
+  /** {@link PackageManagerInstaller.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<PackageManagerInstallerShape>) => Layer.Layer<PackageManagerInstaller>;
+}
+//#endregion
+//#region src/Secret.d.ts
+/**
+ * The declassification seam: the **only** place in this package where a
+ * `Redacted` value becomes a plain string.
+ *
+ * @remarks
+ * Some boundaries cannot carry a `Redacted`. A detached child process reads
+ * its configuration from environment variables; `GITHUB_STATE` is a plaintext
+ * file by GitHub's protocol. `Redacted` refusing to serialize is the whole
+ * value of the type, so this module does not try to make it serializable —
+ * it makes declassification **explicit, auditable, and impossible to do
+ * quietly**.
+ *
+ * The invariant: **masking and declassification are the same call.** Every
+ * member registers the value with the runner's log filter (`::add-mask::`)
+ * *before* returning plaintext, so a secret cannot reach a child's environment
+ * or a state file without the runner already knowing to redact it from logs.
+ *
+ * `Redacted.value` appears nowhere else in this package, and a test asserts
+ * that structurally — a reintroduction elsewhere fails the suite rather than
+ * review.
+ *
+ * What this deliberately does **not** do is encrypt the handoff. The child
+ * runs on the same runner, as the same user, as the parent; a key would have
+ * to travel the same channel as the secret it protects.
+ *
+ * @example
+ * ```ts
+ * import { Secret } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const env = yield* Secret.forChildEnv({ MY_TOKEN: theToken });
+ *   // every value in `env` is already masked in the runner log
+ *   return env;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class Secret {
+  private constructor();
+  /**
+   * Declassify a set of secrets for a child process's environment.
+   *
+   * @remarks
+   * Every value is masked before any plaintext is returned — including when
+   * one of them fails, because masking happens for the whole set first.
+   *
+   * **Detached workers invert the masking model.** Masking works because the
+   * runner parses this process's stdout; a *detached* child's stdout is a log
+   * file no runner parses, so a mask emitted **inside** the worker is inert
+   * and writes the plaintext verbatim into that log — a shipped incident, not
+   * a hypothetical. The rule: **the parent masks, before the spawn** — call
+   * this member in the parent, where the runner is listening, and hand the
+   * already-masked plaintext to the worker's environment. Inside the worker,
+   * compose `ActionOutputs.layerDetached`, whose `setSecret` is a documented
+   * no-op, so the same code cannot re-leak what the parent already masked.
+   */
+  static readonly forChildEnv: (entries: Readonly<Record<string, Redacted.Redacted<string>>>) => Effect.Effect<Record<string, string>, never, ActionOutputs>;
+  /**
+   * Declassify one secret for a runner file (`GITHUB_STATE`, `GITHUB_OUTPUT`).
+   *
+   * @remarks
+   * Masks first. The runner file is plaintext regardless; the mask is what
+   * keeps the value out of the visible log.
+   */
+  static readonly forRunnerFile: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
+  /**
+   * Declassify one secret for an in-process use that needs the raw bytes.
+   *
+   * @remarks
+   * Request signing is the case this exists for: an HMAC cannot be computed
+   * over a `Redacted`, so a signing key has to become a string somewhere, and
+   * the point of this module is that "somewhere" is here and nowhere else.
+   *
+   * Signing named the member; it does not gate it. **Any in-process use that
+   * needs the raw value without writing it to a runner file is this
+   * operation** — handing a key to a library that takes a plain string. The
+   * dividing line is where the value goes, not what it is for: a value
+   * crossing into a **child's** environment is {@link Secret.forChildEnv},
+   * one written to `GITHUB_STATE` or `GITHUB_OUTPUT` is
+   * {@link Secret.forRunnerFile}, and one that stays in this process is this
+   * member. A third-party SDK that reads only the ambient environment is the
+   * hard case: this package never mutates `process.env` (reads are seeded
+   * once through `ActionEnvironment`), so if a consumer chooses that bridge,
+   * the mutation — and its restore discipline — lives in consumer code as
+   * the consumer's own tradeoff, not as a pattern this member recommends.
+   *
+   * It masks even though the value is never *written* anywhere, and that is
+   * deliberate rather than superstitious: a signing key that leaks does so
+   * through something nobody audited — a debug log of outgoing headers, a
+   * serialized error, a stack trace carrying the closure. Registering it with
+   * the runner's filter costs one call and makes every one of those redacted.
+   *
+   * Call it **once, at layer construction**, not per operation: masking is
+   * idempotent but a workflow command per request is noise in the log.
+   *
+   * **In a detached worker, the mask this member emits is a leak.** The
+   * `::add-mask::` command only masks when the runner parses this process's
+   * stdout; a detached worker's stdout is a log file no runner parses, so
+   * there the command masks nothing *and* spells the plaintext into the log
+   * — a signing key shipped exactly that way for one round. A worker that
+   * signs (an S3-style `BlobStore` is the canonical case) must compose
+   * `ActionOutputs.layerDetached`, under which this member still returns the
+   * raw key for the HMAC but the mask is a documented no-op; the masking
+   * itself is the **parent's** job, done before the spawn via
+   * {@link Secret.forChildEnv} under the real layer.
+   */
+  static readonly forSigning: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
+  /**
+   * The far side of a handoff: re-wrap a plaintext environment variable.
+   *
+   * @remarks
+   * A `Config`, so a missing or empty handoff is an honest `ConfigError`
+   * naming the variable rather than an empty `Redacted` that fails much later
+   * as an authentication error.
+   */
+  static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
+}
+//#endregion
+export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, type PackageManagerInstallOptions, PackageManagerInstaller, PackageManagerInstallerError, type PackageManagerInstallerShape, ProcessId, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, type ToolDownloadOptions, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, WorkflowCommand, describeCause, projectCheckState };
 //# sourceMappingURL=index.d.ts.map