@effected/github-actions 0.1.0

package/index.d.ts

@@ -0,0 +1,2467 @@
+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 { BotIdentity, GitHubApp, GitHubClient, InstallationToken, PermissionLevel, RetryPolicy } from "@effected/github";
+//#region src/ActionEnvironment.d.ts
+declare const ActionEnvironmentError_base: Schema.Class<ActionEnvironmentError, Schema.TaggedStruct<"ActionEnvironmentError", {
+  readonly reason: Schema.Literals<readonly ["missing", "malformed"]>;
+  /** The environment variable involved. */
+  readonly name: Schema.String;
+  /** What was wrong, when the reason is `malformed`. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the runner environment does not say what an action needs.
+ *
+ * @remarks
+ * Two reasons, and the distinction is actionable: `missing` means the variable
+ * is absent or empty (the workflow did not grant something, or the action is
+ * running outside Actions); `malformed` means it is present but unusable (a
+ * non-numeric run id, an unparseable event payload). The first is usually a
+ * workflow fix, the second usually a bug report.
+ *
+ * @public
+ */
+declare class ActionEnvironmentError extends ActionEnvironmentError_base {
+  get message(): string;
+}
+declare const GitHubContext_base: Schema.Class<GitHubContext, Schema.Struct<{
+  /** `owner/repo`. */
+  readonly repository: Schema.String;
+  readonly repositoryOwner: Schema.String;
+  /** The full ref, e.g. `refs/heads/main`. */
+  readonly ref: Schema.String;
+  /** The short ref, e.g. `main`. */
+  readonly refName: Schema.String;
+  readonly sha: Schema.String;
+  readonly workflow: Schema.String;
+  readonly job: Schema.String;
+  readonly runId: Schema.Number;
+  readonly runAttempt: Schema.Number;
+  readonly eventName: Schema.String;
+  readonly actor: Schema.String;
+  readonly serverUrl: Schema.String;
+  readonly apiUrl: Schema.String;
+  readonly graphqlUrl: Schema.String;
+  readonly workspace: Schema.String;
+}>, {}>;
+/**
+ * The workflow's GitHub context, projected from the `GITHUB_*` variables.
+ *
+ * @public
+ */
+declare class GitHubContext extends GitHubContext_base {}
+declare const RunnerContext_base: Schema.Class<RunnerContext, Schema.Struct<{
+  readonly os: Schema.String;
+  readonly arch: Schema.String;
+  readonly name: Schema.String;
+  /** A scratch directory emptied between jobs. */
+  readonly temp: Schema.String;
+  /** Where `ToolInstaller` caches toolchains. */
+  readonly toolCache: Schema.String;
+}>, {}>;
+/**
+ * The runner's own context, projected from the `RUNNER_*` variables.
+ *
+ * @public
+ */
+declare class RunnerContext extends RunnerContext_base {}
+/**
+ * The {@link ActionEnvironment} service shape.
+ *
+ * @public
+ */
+interface ActionEnvironmentShape {
+  /** A required variable. Absent or empty fails typed. */
+  readonly get: (name: string) => Effect.Effect<string, ActionEnvironmentError>;
+  /** An optional variable. Empty reads as absent, as the runner treats it. */
+  readonly getOptional: (name: string) => Effect.Effect<Option.Option<string>>;
+  /** The `GITHUB_*` context. */
+  readonly github: Effect.Effect<GitHubContext, ActionEnvironmentError>;
+  /** The `RUNNER_*` context. */
+  readonly runner: Effect.Effect<RunnerContext, ActionEnvironmentError>;
+  /** Whether the runner is in step-debug mode. */
+  readonly isDebug: Effect.Effect<boolean>;
+  /**
+   * The webhook event payload.
+   *
+   * @remarks
+   * `R` is `never`: the layer resolves `FileSystem` once at construction, so
+   * a caller never re-injects one to keep its own requirements clean.
+   */
+  readonly payload: Effect.Effect<unknown, ActionEnvironmentError>;
+  /**
+   * Run an effect with environment overrides applied.
+   *
+   * @remarks
+   * Fiber-local and parallel-safe — `process.env` is never mutated, so
+   * concurrent callers cannot corrupt each other and there is nothing to
+   * restore. Overrides **merge** with any enclosing `withEnv`.
+   *
+   * The trade, stated: a variable exported mid-run by
+   * `ActionOutputs.exportVariable` is not observed here, because the snapshot
+   * is taken once. That matches GitHub's own model, where `exportVariable`
+   * targets *subsequent* steps rather than the running one.
+   */
+  readonly withEnv: <A, E, R>(overrides: Readonly<Record<string, string>>, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const ActionEnvironment_base: Context.ServiceClass<ActionEnvironment, "@effected/github-actions/ActionEnvironment", ActionEnvironmentShape>;
+/**
+ * The runner environment an action is executing inside.
+ *
+ * @remarks
+ * The single reader of `process.env` in this package. Everything else — inputs,
+ * outputs, state, the token bridge — goes through a service rather than
+ * reaching for a global, which is what makes them all testable without
+ * mutating the test process.
+ *
+ * @example
+ * ```ts
+ * import { ActionEnvironment } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const env = yield* ActionEnvironment;
+ *   const { repository, runId } = yield* env.github;
+ *   return `${repository}#${runId}`;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ActionEnvironment extends ActionEnvironment_base {
+  /** Seeded from `process.env`, once, at layer construction. */
+  static readonly layer: Layer.Layer<ActionEnvironment, never, FileSystem.FileSystem>;
+  /**
+   * Seeded from an explicit record.
+   *
+   * @remarks
+   * A parameterized layer factory mints a fresh reference per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  static readonly layerFrom: (env: Readonly<Record<string, string>>) => Layer.Layer<ActionEnvironment, never, FileSystem.FileSystem>;
+  /**
+   * A test double seeded with a complete `GITHUB_*` / `RUNNER_*` block.
+   *
+   * @remarks
+   * **A recorded exception to the die-on-unstubbed rule.** Every other service
+   * in this package dies when a suite calls something it did not stub, because
+   * a plausible default hides a real gap. Here the opposite is true: the twelve
+   * context variables have one obviously-correct shape, and requiring each
+   * suite to restate them produced a byte-identical block duplicated six times
+   * across the consumers. Overrides merge on top.
+   */
+  static readonly makeTest: (overrides?: Readonly<Record<string, string>>) => Effect.Effect<ActionEnvironmentShape, never, FileSystem.FileSystem>;
+  /** {@link ActionEnvironment.makeTest} behind a layer, with `FileSystem` stubbed out. */
+  static readonly layerTest: (overrides?: Readonly<Record<string, string>>) => Layer.Layer<ActionEnvironment>;
+}
+//#endregion
+//#region src/WorkflowCommand.d.ts
+/**
+ * Where an annotation points in the repository.
+ *
+ * @remarks
+ * The field names here are the readable ones; GitHub's wire protocol uses
+ * abbreviations (`line`, `col`) that this module maps on the way out, so a
+ * caller never has to remember which of the six is abbreviated.
+ *
+ * @public
+ */
+interface AnnotationProperties {
+  /** A short title shown above the annotation. */
+  readonly title?: string;
+  /** Repository-relative path of the annotated file. */
+  readonly file?: string;
+  /** First annotated line, 1-based. */
+  readonly startLine?: number;
+  /** Last annotated line, 1-based. */
+  readonly endLine?: number;
+  /** First annotated column, 1-based. */
+  readonly startColumn?: number;
+  /** Last annotated column, 1-based. */
+  readonly endColumn?: number;
+}
+/**
+ * The GitHub Actions workflow-command wire protocol: `::name key=value::message`.
+ *
+ * @remarks
+ * **Pure.** This module renders strings and nothing else — it performs no IO
+ * and holds no service — which is what makes the escaping rules testable
+ * without a runner, and what lets a non-Actions consumer reuse the protocol.
+ * Writing a rendered command to stdout is {@link ActionOutputs}'s job.
+ *
+ * The escaping is the whole point of the module. A message carrying a raw
+ * newline does not merely render oddly: the runner reads the text after it as
+ * a **new command**, so an unescaped log line is a command-injection vector.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowCommand } from "@effected/github-actions";
+ *
+ * WorkflowCommand.error("build failed", { file: "src/main.ts", startLine: 12 });
+ * // "::error file=src/main.ts,line=12::build failed"
+ * ```
+ *
+ * @public
+ */
+declare class WorkflowCommand {
+  private constructor();
+  /**
+   * Render an arbitrary command. The primitive every other member uses.
+   *
+   * @remarks
+   * The property type is written out structurally rather than as the module's
+   * `CommandProperties` alias: an internal named type on a `@public` signature
+   * fails the API Extractor gate, and neither an `@internal` tag nor a second
+   * alias helps — only inlining does.
+   */
+  static render(name: string, properties: Readonly<Record<string, string | number | boolean | undefined>>, message: string): string;
+  /** `::debug::` — shown only when `ACTIONS_STEP_DEBUG` is enabled. */
+  static debug(message: string): string;
+  /** `::notice::` with optional source annotation. */
+  static notice(message: string, properties?: AnnotationProperties): string;
+  /** `::warning::` with optional source annotation. */
+  static warning(message: string, properties?: AnnotationProperties): string;
+  /** `::error::` with optional source annotation. */
+  static error(message: string, properties?: AnnotationProperties): string;
+  /** `::group::` — opens a collapsible section in the runner log. */
+  static group(name: string): string;
+  /** `::endgroup::` — closes the innermost open group. */
+  static endGroup(): string;
+  /** `::add-mask::` — registers a value for redaction in the runner log. */
+  static addMask(value: string): string;
+  /** Map readable annotation fields onto GitHub's abbreviated wire names. */
+  private static annotation;
+}
+//#endregion
+//#region src/ActionLogger.d.ts
+/**
+ * The {@link ActionLogger} service shape.
+ *
+ * @public
+ */
+interface ActionLoggerShape {
+  /** Run an effect inside a collapsible log group. */
+  readonly group: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  /**
+   * Run an effect with its verbose output captured and replayed on exit.
+   *
+   * @remarks
+   * 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.
+   *
+   * 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.
+   */
+  readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  /**
+   * Emit a `::notice::` annotation.
+   *
+   * @remarks
+   * A dedicated member rather than a log level, because Effect has no level
+   * between `Info` and `Warn` to map onto notices.
+   */
+  readonly notice: (message: string, properties?: AnnotationProperties) => Effect.Effect<void>;
+  /**
+   * Attach source annotations to every `Effect.log*` inside an effect.
+   *
+   * @remarks
+   * The point is that a caller never spells an annotation key: the fields go in
+   * as {@link AnnotationProperties} and come out as `file=`/`line=` on the
+   * rendered command.
+   */
+  readonly annotated: <A, E, R>(properties: AnnotationProperties, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const ActionLogger_base: Context.ServiceClass<ActionLogger, "@effected/github-actions/ActionLogger", ActionLoggerShape>;
+/**
+ * Groups, buffered step transcripts, notices — and the `Logger` that renders
+ * every `Effect.log*` in the kit as a workflow command.
+ *
+ * @remarks
+ * The `Logger` is the seam that lets every other `@effected` package stay
+ * telemetry-agnostic: libraries call `Effect.logWarning`, and exactly one
+ * logger — installed at the edge by an action — turns those into `::warning::`
+ * annotations. No library needs to know it is running inside Actions.
+ *
+ * @example
+ * ```ts
+ * import { ActionLogger } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const logger = yield* ActionLogger;
+ *   yield* logger.group("install", logger.withBuffer("pnpm", Effect.logInfo("resolving")));
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ActionLogger extends ActionLogger_base {
+  static readonly layer: Layer.Layer<ActionLogger, never, ActionEnvironment>;
+  /**
+   * The `Logger` that maps Effect log levels onto workflow commands.
+   *
+   * @remarks
+   * `Error` and `Fatal` render `::error::`, `Warn` renders `::warning::`,
+   * `Debug` and `Trace` render `::debug::`, and `Info` renders as plain text.
+   * Annotations set by `annotated` travel with the entry.
+   *
+   * It writes through core `Console`, which is what makes its output
+   * observable in a test without a runner.
+   */
+  static readonly logger: Logger.Logger<unknown, void>;
+  /** {@link ActionLogger.logger} installed as the only logger. */
+  static readonly layerLogger: Layer.Layer<never>;
+  /**
+   * A silent double.
+   *
+   * @remarks
+   * **A recorded exception to the die-on-unstubbed rule**, alongside
+   * {@link ActionEnvironment.makeTest}. A logger that dies when a suite logs
+   * would make every double unusable, and silence is the honest default for a
+   * service whose whole job is output. Group and buffer wrappers pass their
+   * effect through unchanged.
+   */
+  static readonly makeTest: (overrides?: Partial<ActionLoggerShape>) => ActionLoggerShape;
+  /** {@link ActionLogger.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<ActionLoggerShape>) => Layer.Layer<ActionLogger>;
+  /**
+   * A silent service **and** a silent `Effect.log*`.
+   *
+   * @remarks
+   * This one layer replaces the bare `Effect.provide(Logger.layer([]))` that
+   * appeared thirteen times in one consuming action and twenty-three in
+   * another, purely to keep test output quiet. Bound to a constant rather than
+   * exposed as a factory, so composing it twice is free.
+   */
+  static readonly layerSilent: Layer.Layer<ActionLogger>;
+}
+//#endregion
+//#region src/ActionOutputs.d.ts
+declare const ActionOutputError_base: Schema.Class<ActionOutputError, Schema.TaggedStruct<"ActionOutputError", {
+  /**
+   * `unavailable` — the runner file variable is not set, which usually means
+   * 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.
+   */
+  readonly reason: Schema.Literals<readonly ["unavailable", "writeFailed", "invalidName", "encodeFailed"]>;
+  /** Which runner file was involved, by environment variable name. */
+  readonly file: Schema.optionalKey<Schema.String>;
+  /** The output or variable name, when one is involved. */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when an action cannot publish an output.
+ *
+ * @public
+ */
+declare class ActionOutputError extends ActionOutputError_base {
+  get message(): string;
+}
+/**
+ * The {@link ActionOutputs} service shape.
+ *
+ * @public
+ */
+interface ActionOutputsShape {
+  /** Publish a step output. */
+  readonly set: (name: string, value: string) => Effect.Effect<void, ActionOutputError>;
+  /** Publish a step output as JSON, encoded through a schema. */
+  readonly setJson: <A, I>(name: string, value: A, schema: Schema.Codec<A, I>) => Effect.Effect<void, ActionOutputError>;
+  /** Append to the job summary. */
+  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. */
+  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>;
+  /** Register a value for redaction in the runner log. */
+  readonly setSecret: (value: string) => Effect.Effect<void>;
+}
+declare const ActionOutputs_base: Context.ServiceClass<ActionOutputs, "@effected/github-actions/ActionOutputs", ActionOutputsShape>;
+/**
+ * Everything an action publishes: step outputs, exported variables, `PATH`
+ * additions, the job summary, log masking and failure annotations.
+ *
+ * @remarks
+ * Outputs and variables go to the runner's **files** (`GITHUB_OUTPUT` and
+ * friends); masking and annotations go to stdout as workflow commands, through
+ * core `Console` so a test can observe them without a runner.
+ *
+ * `setFailed` emits the annotation but does **not** set the process exit code
+ * — that is `Action.run`'s job, so that an action which reports a failure and
+ * then recovers is not silently doomed by a side effect it cannot undo.
+ *
+ * @public
+ */
+declare class ActionOutputs extends ActionOutputs_base {
+  static readonly layer: Layer.Layer<ActionOutputs, never, ActionEnvironment | FileSystem.FileSystem>;
+  /** A test double. Unstubbed members die rather than silently succeeding. */
+  static readonly makeTest: (overrides?: Partial<ActionOutputsShape>) => ActionOutputsShape;
+  /** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<ActionOutputsShape>) => Layer.Layer<ActionOutputs>;
+}
+//#endregion
+//#region src/ActionState.d.ts
+declare const ActionStateError_base: Schema.Class<ActionStateError, Schema.TaggedStruct<"ActionStateError", {
+  /**
+   * `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
+   * appended to.
+   */
+  readonly reason: Schema.Literals<readonly ["missing", "malformed", "writeFailed"]>;
+  readonly key: Schema.String;
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when state cannot cross the phase boundary.
+ *
+ * @public
+ */
+declare class ActionStateError extends ActionStateError_base {
+  get message(): string;
+}
+/**
+ * The {@link ActionState} service shape.
+ *
+ * @public
+ */
+interface ActionStateShape {
+  /** Persist a value for a later phase. */
+  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>;
+  /** Read a value that may not have been saved. */
+  readonly getOptional: <A, I>(key: string, schema: Schema.Codec<A, I>) => Effect.Effect<Option.Option<A>, ActionStateError>;
+  /**
+   * Persist a secret, masking it in the runner log first.
+   *
+   * @remarks
+   * `GITHUB_STATE` is plaintext by GitHub's protocol — a `Redacted` cannot
+   * survive that boundary by design — so masking is the only available
+   * defense, and coupling it to the write is what makes it unforgettable.
+   */
+  readonly saveSecret: (key: string, secret: string) => Effect.Effect<void, ActionStateError>;
+}
+declare const ActionState_base: Context.ServiceClass<ActionState, "@effected/github-actions/ActionState", ActionStateShape>;
+/**
+ * State that survives the `pre` → `main` → `post` phase boundary.
+ *
+ * @remarks
+ * Each phase of an action is a **separate process**. GitHub's protocol is a
+ * write-only file (`GITHUB_STATE`) whose entries the runner republishes to the
+ * next phase as `STATE_<key>` environment variables — so saving and reading go
+ * through different mechanisms, which is why this is a service rather than a
+ * pair of helpers.
+ *
+ * @public
+ */
+declare class ActionState extends ActionState_base {
+  static readonly layer: Layer.Layer<ActionState, never, ActionEnvironment | FileSystem.FileSystem | ActionOutputs>;
+  /** A test double. Unstubbed members die rather than answering wrongly. */
+  static readonly makeTest: (overrides?: Partial<ActionStateShape>) => ActionStateShape;
+  /** {@link ActionState.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<ActionStateShape>) => Layer.Layer<ActionState>;
+}
+//#endregion
+//#region src/Action.d.ts
+/**
+ * Everything {@link ActionRuntime.layer} provides.
+ *
+ * @remarks
+ * Spelled out rather than inferred so a caller can name it — a program written
+ * against `ActionServices` is a program `Action.run` can run, and the compiler
+ * says so before the runner does.
+ *
+ * @public
+ */
+type ActionServices = ActionEnvironment | ActionLogger | ActionOutputs | ActionState | NodeServices.NodeServices | HttpClient.HttpClient;
+/**
+ * The default runtime an action executes inside.
+ *
+ * @remarks
+ * The one place in the kit where `@effect/platform-node` is composed rather
+ * than left to the consumer, and the reason is that there is no second answer:
+ * a GitHub Action is a Node process on a GitHub-provided runner.
+ *
+ * **The cache, artifact and blob services are deliberately NOT in here.** They
+ * are the only modules that import `@azure/storage-blob`, and folding them into
+ * the default runtime would put a blob-storage client in the bundle of every
+ * action that merely sets an output. Their requirements are all satisfied by
+ * this layer, so taking one costs a caller exactly one line:
+ * `Action.run(program, { layer: ActionCache.layer })`.
+ *
+ * @public
+ */
+declare class ActionRuntime {
+  private constructor();
+  /**
+   * The composed default: the runner services, the platform, an HTTP client
+   * and the workflow-command `Logger`.
+   *
+   * @remarks
+   * A bound constant rather than a factory. A layer-returning function mints a
+   * fresh layer per call, and layers memoize by reference — a factory here
+   * would rebuild the environment snapshot for every composition site.
+   */
+  static readonly layer: Layer.Layer<ActionServices>;
+}
+/**
+ * How to run an action.
+ *
+ * @public
+ */
+interface ActionRunOptions<R> {
+  /**
+   * Services the program needs beyond {@link ActionServices}.
+   *
+   * @remarks
+   * It may require anything {@link ActionRuntime.layer} provides — which is
+   * what makes `{ layer: ActionCache.layer }` compile with no further wiring.
+   */
+  readonly layer?: Layer.Layer<R, never, ActionServices> | undefined;
+}
+/**
+ * A readable one-line summary of why an action failed.
+ *
+ * @remarks
+ * `[Tag] message` because a workflow log is read by a human scanning for the
+ * first red line, and every error in this kit carries both. The `_tag` is what
+ * makes two failures with the same wording distinguishable, and the `message`
+ * getter is what makes the line worth reading.
+ *
+ * An interruption has neither, and `Cause.pretty` is the honest answer for it.
+ *
+ * @public
+ */
+declare const describeCause: (cause: Cause.Cause<unknown>) => string;
+/**
+ * The entry point an action's `main`, `pre` and `post` scripts call.
+ *
+ * @remarks
+ * Everything an action entry point does that is not the action: compose the
+ * runtime, run the program, render a failure as a `::error::` annotation, and
+ * **set the exit code** — which is the piece
+ * `ActionOutputs.setFailed` deliberately leaves alone, so an action that
+ * reports a failure and then recovers is not doomed by a side effect it cannot
+ * undo.
+ *
+ * Two things it deliberately does **not** do:
+ *
+ * - **It does not wrap the program in a log buffer.** The package this replaces
+ *   did, and an unhandled defect inside the buffer swallowed the entire
+ *   transcript — the run failed and printed nothing. `ActionLogger.withBuffer`
+ *   is opt-in and flushes on every exit path including a defect, so the
+ *   buffering is where the caller can see it.
+ * - **It does not throw.** The returned promise always resolves; the failure is
+ *   in `process.exitCode`, which is what the runner reads. An action entry
+ *   point that rejected would produce an unhandled rejection *and* a failed
+ *   step, and only the first would be legible.
+ *
+ * The rendering depth is deliberate too: one `::error::` line carrying
+ * `[Tag]: message`, and the fiddly diagnostics — the full `Cause.pretty` render
+ * with its span trace and stack — behind `::debug::`, which the runner shows
+ * only when someone turns step debugging on. The package this replaces spliced
+ * a JS stack into the visible error, which in a bundled action points at one
+ * line of `dist/main.js`.
+ *
+ * @example
+ * ```ts
+ * import { Action, ActionCache } from "@effected/github-actions";
+ *
+ * await Action.run(program, { layer: ActionCache.layer });
+ * ```
+ *
+ * @public
+ */
+declare class Action {
+  private constructor();
+  /** {@link describeCause}, so an action can render its own failures the same way. */
+  static readonly describeCause: (cause: Cause.Cause<unknown>) => string;
+  /**
+   * Run an action program to completion.
+   *
+   * @remarks
+   * Resolves whether the program succeeded or not; read `process.exitCode` for
+   * the verdict.
+   */
+  static readonly run: <E, R = never>(program: Effect.Effect<void, E, ActionServices | R>, options?: ActionRunOptions<R>) => Promise<void>;
+}
+//#endregion
+//#region src/BlobTransfer.d.ts
+declare const BlobTransferError_base: Schema.Class<BlobTransferError, Schema.TaggedStruct<"BlobTransferError", {
+  /** Which direction failed. */
+  readonly reason: Schema.Literals<readonly ["uploadFailed", "downloadFailed"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when bytes could not be moved to or from a signed blob url.
+ *
+ * @public
+ */
+declare class BlobTransferError extends BlobTransferError_base {
+  get message(): string;
+}
+/**
+ * Moving whole files to and from the signed blob url a results-backend RPC
+ * hands back.
+ *
+ * @remarks
+ * The seam exists because the *protocol* is what this package owns and the
+ * *transport* is not: the Actions results backend answers a Twirp RPC with a
+ * pre-signed Azure url, and everything interesting — the RPC sequence, the
+ * conflict handling, the retry policy, the version hash — happens on this side
+ * of it. Taking the transport as an argument means all of that is exercised by
+ * a test rather than described by one, and the Azure client stays confined to
+ * the three modules permitted to import it.
+ *
+ * A url is a plain string on purpose: it is a **credential** (the signature is
+ * in the query), and it is never logged, annotated on a span, or carried on an
+ * error.
+ *
+ * @public
+ */
+interface FileBlobTransfer {
+  /** Upload a file's contents to the url. */
+  readonly uploadFile: (url: string, file: string) => Effect.Effect<void, BlobTransferError>;
+  /** Download the url's contents into a file. */
+  readonly downloadToFile: (url: string, file: string) => Effect.Effect<void, BlobTransferError>;
+}
+/**
+ * Moving in-memory bytes to and from a signed blob url.
+ *
+ * @remarks
+ * The {@link FileBlobTransfer} counterpart for payloads that never touch the
+ * filesystem. Split rather than merged because the cache and artifact protocols
+ * only ever move files and the blob store only ever moves buffers — a single
+ * four-member interface would make every implementation stub two members it can
+ * never be asked for.
+ *
+ * @public
+ */
+interface DataBlobTransfer {
+  /** Upload bytes to the url. */
+  readonly uploadData: (url: string, data: Uint8Array) => Effect.Effect<void, BlobTransferError>;
+  /** Download the url's contents. */
+  readonly downloadToBuffer: (url: string) => Effect.Effect<Uint8Array, BlobTransferError>;
+}
+//#endregion
+//#region src/CacheKey.d.ts
+declare const CacheKeyError_base: Schema.Class<CacheKeyError, Schema.TaggedStruct<"CacheKeyError", {
+  /**
+   * `readFailed` — a file or directory that was going to be hashed could not be
+   * read. `badPattern` — a glob pattern would not compile. Key *derivation*
+   * itself is pure and total once the bytes are in hand, so these are the only
+   * two things that can go wrong.
+   */
+  readonly reason: Schema.Literals<readonly ["readFailed", "badPattern"]>;
+  /** The path being read when it went wrong. */
+  readonly path: Schema.optionalKey<Schema.String>;
+  /** The pattern that would not compile. */
+  readonly pattern: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a cache key cannot be derived from the filesystem.
+ *
+ * @public
+ */
+declare class CacheKeyError extends CacheKeyError_base {
+  get message(): string;
+}
+declare const CacheKey_base: Schema.Class<CacheKey, Schema.Struct<{
+  /** The components, most general first. */
+  readonly segments: Schema.NonEmptyArray<Schema.String>;
+}>, {}>;
+/**
+ * A GitHub Actions cache key and the restore-key ladder that goes with it.
+ *
+ * @remarks
+ * The ladder is the part every consumer re-derives and gets subtly wrong. A
+ * restore key is a **prefix match** on GitHub's side, so `Linux-pnpm` would
+ * also match `Linux-pnpm-store-…` from an unrelated cache; every rung here
+ * therefore ends in the separator. Deriving the rungs from the segments makes
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { CacheKey } from "@effected/github-actions";
+ *
+ * const key = CacheKey.of("Linux", "pnpm-store", "abc123");
+ * key.key;          // "Linux-pnpm-store-abc123"
+ * key.restoreKeys;  // ["Linux-pnpm-store-", "Linux-"]
+ * ```
+ *
+ * @public
+ */
+declare class CacheKey extends CacheKey_base {
+  /** The primary key: every segment, joined. */
+  get key(): string;
+  /**
+   * 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.
+   */
+  get restoreKeys(): ReadonlyArray<string>;
+  /** Build a key from its segments. */
+  static of(...segments: readonly [string, ...ReadonlyArray<string>]): CacheKey;
+  /**
+   * A branch-aware key.
+   *
+   * @remarks
+   * Ordering the segments `os → scope → branch → hash` is what makes the
+   * derived ladder do the right thing: the first rung falls back to any earlier
+   * cache **on this branch**, and only the next one reaches across branches. The
+   * reverse order would make the first fallback jump branches, which is how a
+   * feature branch ends up warming its cache from `main` and never noticing its
+   * own.
+   *
+   * Every part is an explicit argument rather than read from the environment,
+   * so a key is reproducible outside a runner and a test needs no ambient
+   * state.
+   */
+  static forBranch(options: {
+    /** What is being cached, e.g. `"pnpm-store"`. */
+    readonly scope: string;
+    /** The short ref, e.g. `GITHUB_REF_NAME`. */
+    readonly branch: string;
+    /** The runner OS, e.g. `RUNNER_OS`. Included first when given. */
+    readonly os?: string;
+    /** The content hash, e.g. from {@link CacheKey.hashFiles}. Included last when given. */
+    readonly hash?: string;
+  }): CacheKey;
+  /**
+   * Hash a set of files into a single digest.
+   *
+   * @remarks
+   * **Byte-compatible with `@actions/glob`'s `hashFiles`**, and the three
+   * details that make it so are all easy to get wrong: the paths are sorted, each
+   * file is hashed on its own, and the per-file digest is fed into the
+   * accumulator as **binary** rather than hex. A hex-fed accumulator produces a
+   * perfectly plausible digest that simply never matches a cache entry written
+   * by any other action.
+   *
+   * Sorting and de-duplication happen here rather than at the call site, so a
+   * caller cannot accidentally make its key depend on the order it discovered
+   * files in.
+   *
+   * `Option.none()` for an empty set, because "nothing matched" is not a
+   * digest — it is the signal that the pattern is wrong, and a caller that
+   * folds it into a key silently caches against a constant.
+   */
+  static readonly hashFiles: (files: readonly string[]) => Effect.Effect<Option.Option<string>, CacheKeyError, FileSystem.FileSystem>;
+  /**
+   * Every file under `workspace` that the pattern set matches.
+   *
+   * @remarks
+   * Discovery and matching are **two different jobs**, and separating them is
+   * what makes this testable and correct. The walk is core
+   * `FileSystem.readDirectory(recursive)`; the matching is `@effected/glob`'s
+   * full minimatch dialect — the same dialect `@actions/glob` uses, so a workflow
+   * author's `!**\/node_modules/**` behaves here exactly as it does in every
+   * other cache step in the same workflow. `node:fs.globSync` would have welded
+   * the two together behind one non-stubbable call *and* changed the dialect,
+   * and a dialect divergence surfaces as a silent cache-key difference — the
+   * worst failure mode a cache key has.
+   *
+   * Candidates are matched by their path **relative to the workspace**, which
+   * is what makes "never hash a file outside the workspace" structural rather
+   * than a rule someone has to remember. Directories are excluded: a directory
+   * called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
+   * would fail rather than being ignored.
+   *
+   * The answer is sorted, so a caller cannot make its key depend on the order
+   * the filesystem happened to report.
+   */
+  static readonly matchingFiles: (options: {
+    /** The directory to walk. Nothing outside it is ever considered. */
+    readonly workspace: string;
+    /** Include patterns, with a leading `!` marking an exclusion. */
+    readonly patterns: ReadonlyArray<string>;
+  }) => Effect.Effect<readonly string[], CacheKeyError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * Hash every file under `workspace` that the pattern set matches.
+   *
+   * @remarks
+   * {@link CacheKey.matchingFiles} into {@link CacheKey.hashFiles}, which is
+   * the pairing every consumer writes by hand — and the pairing whose two
+   * halves have to agree about ordering and about what counts as a file for the
+   * digest to match anything anyone else computed.
+   *
+   * `Option.none()` when nothing matched, for the same reason `hashFiles` gives:
+   * "no files" is not a digest, it is the signal that the patterns are wrong,
+   * and folding it into a key silently caches against a constant.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   * import { Effect, Option } from "effect";
+   *
+   * const key = Effect.gen(function* () {
+   *   const hash = yield* CacheKey.hashMatching({
+   *     workspace: "/home/runner/work/repo/repo",
+   *     patterns: ["**\/pnpm-lock.yaml", "!**\/node_modules/**"],
+   *   });
+   *   return CacheKey.of("Linux", "pnpm-store", Option.getOrElse(hash, () => "empty"));
+   * });
+   * ```
+   */
+  static readonly hashMatching: (options: {
+    readonly workspace: string;
+    readonly patterns: ReadonlyArray<string>;
+  }) => Effect.Effect<Option.Option<string>, CacheKeyError, FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/ActionCache.d.ts
+declare const ActionCacheError_base: Schema.Class<ActionCacheError, Schema.TaggedStruct<"ActionCacheError", {
+  /**
+   * `misconfigured` — the results backend is not reachable from here (see
+   * {@link ActionCache}). `unreachable` — it could not be contacted, or
+   * answered with something that is not a Twirp body. `refused` — it answered,
+   * unhappily. `archiveFailed` — `tar` would not pack or unpack the paths.
+   * `transferFailed` — the archive itself did not move.
+   */
+  readonly reason: Schema.Literals<readonly ["misconfigured", "unreachable", "refused", "archiveFailed", "transferFailed"]>;
+  /** The cache key involved. A stable identifier, never a value. */
+  readonly key: Schema.optionalKey<Schema.String>;
+  /** The HTTP status, when the backend answered. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** What went wrong, when the reason alone does not say. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** `tar`'s own complaint, which is the only useful part of an archive failure. */
+  readonly stderr: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the runner's cache cannot be read or written.
+ *
+ * @public
+ */
+declare class ActionCacheError extends ActionCacheError_base {
+  get message(): string;
+}
+/**
+ * The {@link ActionCache} service shape.
+ *
+ * @public
+ */
+interface ActionCacheShape {
+  /**
+   * Archive `paths` and store them under `key`.
+   *
+   * @remarks
+   * 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.
+   */
+  readonly save: (paths: ReadonlyArray<string>, key: string | CacheKey) => Effect.Effect<void, ActionCacheError>;
+  /**
+   * Restore `paths` from the first entry that matches, and answer with the key
+   * that matched.
+   *
+   * @remarks
+   * `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".
+   */
+  readonly restore: (paths: ReadonlyArray<string>, key: string | CacheKey, restoreKeys?: ReadonlyArray<string>) => Effect.Effect<Option.Option<string>, ActionCacheError>;
+}
+declare const ActionCache_base: Context.ServiceClass<ActionCache, "@effected/github-actions/ActionCache", ActionCacheShape>;
+/**
+ * The runner's own cache: archive a set of paths under a key, and get them back
+ * in a later job.
+ *
+ * @remarks
+ * Speaks the Actions cache **Twirp v2** protocol at `ACTIONS_RESULTS_URL`,
+ * which answers with a pre-signed Azure blob url for the archive itself. No
+ * `@actions/cache` dependency — that package alone brings a dependency tree
+ * larger than this one.
+ *
+ * **Only reachable from a `uses:` step.** The runner injects
+ * `ACTIONS_RESULTS_URL` and `ACTIONS_RUNTIME_TOKEN` into action execution
+ * contexts and not into `run:` shell steps, so the identical code fails as
+ * `misconfigured` when a workflow invokes it with `node ./main.js`. The failure
+ * names the absent variable, because nothing else distinguishes the two cases.
+ *
+ * @example
+ * ```ts
+ * import { ActionCache, CacheKey } from "@effected/github-actions";
+ * import { Effect, Option } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* ActionCache;
+ *   const key = CacheKey.of("Linux", "pnpm-store", "abc123");
+ *   const hit = yield* cache.restore(["~/.pnpm-store"], key);
+ *   if (Option.isNone(hit)) {
+ *     yield* cache.save(["~/.pnpm-store"], key);
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ActionCache extends ActionCache_base {
+  /** The cache, over the real Azure client and the real `tar`. */
+  static readonly layer: Layer.Layer<ActionCache, never, ActionEnvironment | HttpClient.HttpClient | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * The cache, over a supplied transport.
+   *
+   * @remarks
+   * The protocol, the version derivation, the conflict handling and the archive
+   * are what this package owns; the pre-signed `PUT` is not. Supplying the
+   * transport is what lets a test exercise all of the first group without the
+   * second, and what an integration test uses to point the same protocol at a
+   * local blob endpoint.
+   *
+   * A parameterized layer factory mints a fresh layer per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  static readonly layerWith: (transfer: FileBlobTransfer) => Layer.Layer<ActionCache, never, ActionEnvironment | HttpClient.HttpClient | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /** A test double. Unstubbed members die rather than reporting a miss. */
+  static readonly makeTest: (overrides?: Partial<ActionCacheShape>) => ActionCacheShape;
+  /** {@link ActionCache.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<ActionCacheShape>) => Layer.Layer<ActionCache>;
+}
+//#endregion
+//#region src/ActionInput.d.ts
+/**
+ * Action inputs, read as `Config` values.
+ *
+ * @remarks
+ * Inputs are **never** read from `process.env` directly. Every accessor names
+ * the input the way the workflow author wrote it and lets this module derive
+ * the runner's variable name — see `inputVariable` for why that matters. (A
+ * `{@link}` cannot reach it: it is internal, so it is not exported from the
+ * entrypoint and the reference would not resolve.)
+ *
+ * `lines`, `list` and `pairs` exist because the `@actions/core`-faithful
+ * newline split was not enough for real consumers: two of them reinvented
+ * richer parsing independently, one parsing JSON arrays and bullet lists, the
+ * other stripping comments and reading `key=value` pairs. Those are now one
+ * implementation with one set of tests instead of two divergent ones with
+ * none.
+ *
+ * These are grouped statics over one concept reaching nothing but `Config` —
+ * not a namespace object over engines.
+ *
+ * **The absence contract, shared by every accessor:** the runner writes `""`
+ * for an input the workflow left out, and the provider reads an empty string
+ * as absent — so *unset* and *empty* are the same case, **missing data**, and
+ * the read fails rather than yielding an empty value. `Config.withDefault`
+ * falls back for exactly that class, which makes
+ * `.pipe(Config.withDefault(…))` the idiom for every optional input. What a
+ * default never swallows is a *present but malformed* value — see
+ * {@link ActionInput.boolean}.
+ *
+ * @example
+ * ```ts
+ * import { ActionInput } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const dryRun = yield* ActionInput.boolean("dry-run");
+ *   const globs = yield* ActionInput.list("paths");
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ActionInput {
+  private constructor();
+  /**
+   * A required string input.
+   *
+   * @remarks
+   * Fails as *missing data* when the input is absent **or set to the empty
+   * string** — the runner writes `""` for an unsupplied input, and both the
+   * runtime's provider and {@link ActionInput.provider} read that as absent.
+   * Every accessor on this class shares the rule, so an **optional** input
+   * needs `Config.withDefault` (or `Config.option`) at the call site or the
+   * read fails outright.
+   */
+  static string(name: string): Config.Config<string>;
+  /**
+   * A boolean input, per the runner's documented YAML 1.2 core schema.
+   *
+   * @remarks
+   * Absent or `""` is **missing data** — wrap with `Config.withDefault` for
+   * an optional flag. A **present but malformed** value (`yes`, `on`, `1`) is
+   * a different class: it fails carrying its `actual`, deliberately, so a
+   * default does NOT swallow it — the shipped defect this guards against was
+   * a malformed `dry-run` quietly reading as `false`.
+   */
+  static boolean(name: string): Config.Config<boolean>;
+  /**
+   * An integer input.
+   *
+   * @remarks
+   * Unset and `""` both fail as **missing data**; for an optional input,
+   * `.pipe(Config.withDefault(n))`.
+   */
+  static integer(name: string): Config.Config<number>;
+  /**
+   * A secret input, kept redacted.
+   *
+   * @remarks
+   * Unset and `""` both fail as **missing data**; `Config.option` is the
+   * usual shape for an optional secret, since there is rarely a meaningful
+   * default to redact.
+   */
+  static redacted(name: string): Config.Config<Redacted.Redacted<string>>;
+  /**
+   * A multiline input, split on newlines.
+   *
+   * @remarks
+   * The `@actions/core`-faithful shape: blank lines are dropped and each entry
+   * is trimmed, because a YAML block scalar carries the workflow's own
+   * indentation.
+   *
+   * Absent or `""` fails as missing data (see {@link ActionInput.string}) —
+   * `Config.withDefault([])` is load-bearing for an optional multiline input.
+   */
+  static lines(name: string): Config.Config<ReadonlyArray<string>>;
+  /**
+   * A list input, accepting the shapes workflow authors actually write.
+   *
+   * @remarks
+   * A JSON array (`["a","b"]`), a bullet list (`- a` or `* a`), or comma- and
+   * newline-separated values, with full-line `#` comments dropped — any
+   * combination of these in the same input. Each shape was reinvented
+   * independently by a consumer (one a bullet-list-and-JSON parser, the other
+   * comment-stripping); accepting the union means a workflow author's first
+   * guess works and nothing either prior consumer relied on regresses.
+   *
+   * Parsing order, applied per newline/comma-separated item after trimming:
+   *
+   * 1. **Comment lines are dropped first.** A trimmed item whose first
+   *    character is `#` is a full-line comment and is discarded entirely,
+   *    before any bullet marker is considered. This means `- #tag` is a
+   *    value, not a comment: the check runs on the untouched, still-bulleted
+   *    item, and `-` is not `#`.
+   * 2. **Only then is a leading bullet marker stripped** — `- ` or `* `
+   *    (dash-or-asterisk followed by a space), mirroring the indentation a
+   *    YAML block scalar carries in. So `- #tag` becomes the value `#tag`.
+   * 3. Blank results (an empty line, or a comment line) are dropped from the
+   *    final list.
+   *
+   * A `#` that is not the first character of a trimmed item — a trailing or
+   * mid-value `#` — is left alone; unlike {@link ActionInput.pairs}, `list`
+   * has no trailing-comment rule, only a whole-line one.
+   *
+   * Absent or `""` fails as **missing data** (see {@link ActionInput.string}),
+   * so `Config.withDefault([])` is load-bearing at every optional-input call
+   * site — omitting an optional multi-value input otherwise fails the read
+   * outright. A *whitespace-only* value (a block scalar holding only a
+   * newline) is present, and parses to `[]`.
+   */
+  static list(name: string): Config.Config<ReadonlyArray<string>>;
+  /**
+   * A `key=value` input, one pair per line, with `#` comments stripped.
+   *
+   * @remarks
+   * Only the **first** `=` splits, so a value may contain one.
+   *
+   * Absent or `""` fails as missing data (see {@link ActionInput.string}) —
+   * `Config.withDefault({})` is the idiom for an optional pairs input.
+   */
+  static pairs(name: string): Config.Config<Record<string, string>>;
+  /**
+   * A JSON-valued input, decoded through a schema.
+   *
+   * @remarks
+   * Absent or `""` fails as **missing data** before any JSON parsing runs
+   * (see {@link ActionInput.string}) — `Config.withDefault` or
+   * `Config.option` for an optional input. A present value that is not valid
+   * JSON, or does not satisfy the schema, fails carrying its `actual` and is
+   * never swallowed by a default.
+   */
+  static schema<A, I>(name: string, schema: Schema.Codec<A, I>): Config.Config<A>;
+  /**
+   * A `ConfigProvider` over a record of runner variables.
+   *
+   * @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.
+   *
+   * Taking the environment as an argument rather than reading `process.env`
+   * is what makes inputs testable without mutating the test process.
+   */
+  static provider(env?: Readonly<Record<string, string | undefined>>): ConfigProvider.ConfigProvider;
+  /**
+   * A layer installing {@link ActionInput.provider}.
+   *
+   * @remarks
+   * `ConfigProvider.ConfigProvider` is a `Context.Reference` in v4, so this is
+   * a reference override rather than a service — there is no
+   * `Effect.withConfigProvider`.
+   *
+   * A parameterized layer factory mints a fresh reference per call; bind it to
+   * a `const` rather than calling it at each composition site.
+   */
+  static layer(env?: Readonly<Record<string, string | undefined>>): Layer.Layer<never>;
+  /**
+   * Inputs-first resolution layered over an existing provider.
+   *
+   * @remarks
+   * A bare `Config.string("dry-run")` resolves a **flat** name — one string
+   * segment — by first trying the variable the runner would have published for
+   * an input of that name (the `INPUT_` derivation this module owns), and only
+   * then trying the name unchanged through `ambient`. Anything the runner
+   * could not have set as an input — a nested path, a numeric segment — is
+   * passed to `ambient` untouched, so no path semantics are invented that the
+   * runner does not have.
+   *
+   * This exists because a live action shipped a **false green**: every bare
+   * `Config` read fell back to its `withDefault` because the runner exposes
+   * inputs as `INPUT_<MANGLED>` variables and a plain-named lookup finds
+   * nothing. Under this provider a bare read resolves through the same
+   * derivation `ActionInput.string` uses, so side-stepping the typed accessors
+   * degrades to the right answer instead of to the default.
+   *
+   * The documented trade: a workflow input named like an environment variable
+   * **shadows it** for bare reads — and because the derivation uppercases,
+   * any casing of the name sees the input. An unsupplied input does not
+   * shadow: the runner writes `""` for it, and the ambient provider's
+   * empty-is-absent rule (which the attempt resolves through) drops it. The
+   * `ActionInput` accessors themselves are unaffected — they read
+   * `INPUT_<MANGLED>` names, whose re-mangled form (`INPUT_INPUT_…`) never
+   * matches, so they fall through to the ambient lookup they always used.
+   */
+  static providerOver(ambient: ConfigProvider.ConfigProvider): ConfigProvider.ConfigProvider;
+  /**
+   * The provider the default action runtime installs: {@link ActionInput.providerOver}
+   * composed over the ambient environment lookup.
+   *
+   * @remarks
+   * Installed by `ActionRuntime.layer`, and therefore by `Action.run` — a bare
+   * `Config` read inside an action resolves through the runner's `INPUT_`
+   * derivation instead of silently missing. A caller-supplied
+   * `ConfigProvider` layer still wins by normal layer precedence.
+   *
+   * The ambient half is whatever provider is **explicitly installed** when the
+   * layer builds — which is how a test injects a deterministic environment by
+   * providing `ConfigProvider.layer(ConfigProvider.fromEnv({ env }))` beneath
+   * the runtime. When none is installed, a **fresh** `ConfigProvider.fromEnv()`
+   * is built rather than reading the reference's default: v4 caches that
+   * default once per process, and a snapshot taken before the runner's
+   * variables are visible would resurrect exactly the missed-input class this
+   * layer exists to kill. An action's environment is fixed before the process
+   * starts, so production cannot tell the difference; a test mutating
+   * `process.env` around `Action.run` can.
+   *
+   * A bound constant rather than a factory: layers memoize by reference.
+   */
+  static readonly layerDefault: Layer.Layer<never>;
+}
+//#endregion
+//#region src/Artifact.d.ts
+declare const ArtifactError_base: Schema.Class<ArtifactError, Schema.TaggedStruct<"ArtifactError", {
+  /**
+   * `misconfigured` — the results backend is not reachable from here (see
+   * {@link Artifact}). `unreachable` — it could not be contacted, or answered
+   * with something that is not a Twirp body. `refused` — it answered,
+   * unhappily; re-uploading a name that already exists in the run is the
+   * common case. `notFound` — no artifact by that name or id exists in this
+   * run. `archiveFailed` — `zip` would not pack or unpack the files.
+   * `transferFailed` — the archive itself did not move. `invalidOptions` — the
+   * call cannot be made as asked.
+   */
+  readonly reason: Schema.Literals<readonly ["misconfigured", "unreachable", "refused", "notFound", "archiveFailed", "transferFailed", "invalidOptions"]>;
+  /** The artifact's name or id. A stable identifier, never a value. */
+  readonly artifact: Schema.optionalKey<Schema.String>;
+  /** The HTTP status, when the backend answered. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** What went wrong, when the reason alone does not say. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** `zip`'s own complaint, which is the only useful part of an archive failure. */
+  readonly stderr: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when an artifact cannot be uploaded, listed, downloaded or deleted.
+ *
+ * @public
+ */
+declare class ArtifactError extends ArtifactError_base {
+  get message(): string;
+}
+/**
+ * One artifact, as the backend describes it.
+ *
+ * @public
+ */
+interface ArtifactItem {
+  /** The database id, which is what `download` takes. */
+  readonly id: number;
+  readonly name: string;
+  /** The size of the stored zip, in bytes. */
+  readonly size: number;
+  /** When it was created, ISO-8601, when the backend says. */
+  readonly createdAt?: string | undefined;
+}
+/**
+ * How to pack an upload.
+ *
+ * @public
+ */
+interface UploadOptions {
+  /**
+   * How long to keep it, in days.
+   *
+   * @remarks
+   * Bounded by the repository's own retention setting; omitted means the
+   * repository default. Zero or negative fails as `invalidOptions` rather than
+   * being silently corrected, because "delete it immediately" and "keep it for
+   * the default period" are too far apart to guess between.
+   */
+  readonly retentionDays?: number | undefined;
+  /**
+   * The zlib level, 0–9, defaulting to 6 as `@actions/artifact` does.
+   *
+   * @remarks
+   * Out-of-range values are clamped. No effect on Windows, where
+   * `Compress-Archive` has no numeric equivalent.
+   */
+  readonly compressionLevel?: number | undefined;
+}
+/**
+ * What an upload produced.
+ *
+ * @public
+ */
+interface UploadResult {
+  readonly id: number;
+  /** The size of the uploaded zip, in bytes. */
+  readonly size: number;
+}
+/**
+ * Where a download should land.
+ *
+ * @public
+ */
+interface DownloadOptions {
+  /** The destination directory. A fresh temporary directory when omitted. */
+  readonly path?: string | undefined;
+}
+/**
+ * What a download produced.
+ *
+ * @public
+ */
+interface DownloadResult {
+  /** The directory the artifact's contents were extracted into. */
+  readonly downloadPath: string;
+}
+/**
+ * A reference to an artifact that is no longer there.
+ *
+ * @public
+ */
+interface ArtifactRef {
+  readonly id: number;
+}
+/**
+ * The {@link Artifact} service shape.
+ *
+ * @public
+ */
+interface ArtifactShape {
+  /**
+   * Zip `files` — paths under `rootDirectory` — and upload them under `name`.
+   *
+   * @remarks
+   * Entries are stored relative to `rootDirectory`, so what a later download
+   * extracts is the layout the caller meant rather than its absolute path on
+   * whichever runner produced it. A name already used in this run is refused by
+   * the backend: artifacts are immutable within a run.
+   */
+  readonly upload: (name: string, files: ReadonlyArray<string>, rootDirectory: string, options?: UploadOptions) => Effect.Effect<UploadResult, ArtifactError>;
+  /** Every artifact in the current run. */
+  readonly list: () => Effect.Effect<ReadonlyArray<ArtifactItem>, ArtifactError>;
+  /** One artifact by name, or nothing — absent is not a failure. */
+  readonly get: (name: string) => Effect.Effect<Option.Option<ArtifactItem>, ArtifactError>;
+  /** Download an artifact by id and unzip it. Answers with where it landed. */
+  readonly download: (artifactId: number, options?: DownloadOptions) => Effect.Effect<DownloadResult, ArtifactError>;
+  /** Delete an artifact by name, answering with the id that is now gone. */
+  readonly delete: (name: string) => Effect.Effect<ArtifactRef, ArtifactError>;
+}
+declare const Artifact_base: Context.ServiceClass<Artifact, "@effected/github-actions/Artifact", ArtifactShape>;
+/**
+ * Upload, list, download and delete GitHub Actions artifacts.
+ *
+ * @remarks
+ * Speaks the artifact **Twirp v2** protocol at `ACTIONS_RESULTS_URL`, which
+ * answers with a pre-signed Azure blob url for the zip. No `@actions/artifact`
+ * dependency.
+ *
+ * **Only reachable from a `uses:` step**, like {@link ActionCache} — the two
+ * variables it needs are injected into action execution contexts and not into
+ * `run:` shell steps. The `Actions.Results` scope inside the runtime token is a
+ * third thing that can be absent, and it is reported as `misconfigured` for the
+ * same reason.
+ *
+ * **This surface is provisional.** Unlike every other service here it was
+ * ported without a call site to shape it against, so it keeps the source's
+ * shape rather than a narrower one invented from nothing. The first consumer to
+ * adopt it is the one whose feedback reshapes it — the members lost their
+ * `Artifact` prefix (`artifact.uploadArtifact(...)` stutters) and the
+ * cross-run `findBy` lookup is **not** ported, because every path through it in
+ * the source is a typed "not implemented" failure. Adding it later is additive;
+ * shipping a parameter that has never had behavior is not.
+ *
+ * @example
+ * ```ts
+ * import { Artifact } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const artifacts = yield* Artifact;
+ *   return yield* artifacts.upload("logs", ["/tmp/build/log.txt"], "/tmp/build");
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class Artifact extends Artifact_base {
+  /** The service, over the real Azure client and the real `zip`. */
+  static readonly layer: Layer.Layer<Artifact, never, ActionEnvironment | HttpClient.HttpClient | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * The service, over a supplied transport.
+   *
+   * @remarks
+   * The protocol, the zip, the digest and the conflict handling are what this
+   * package owns; the pre-signed `PUT` is not. Supplying the transport is what
+   * lets a test exercise all of the first group without the second.
+   *
+   * A parameterized layer factory mints a fresh layer per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  static readonly layerWith: (transfer: FileBlobTransfer) => Layer.Layer<Artifact, never, ActionEnvironment | HttpClient.HttpClient | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /** A test double. Unstubbed members die rather than reporting an empty run. */
+  static readonly makeTest: (overrides?: Partial<ArtifactShape>) => ArtifactShape;
+  /** {@link Artifact.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<ArtifactShape>) => Layer.Layer<Artifact>;
+}
+//#endregion
+//#region src/BlobEnvelope.d.ts
+declare const BlobEnvelopeError_base: Schema.Class<BlobEnvelopeError, Schema.TaggedStruct<"BlobEnvelopeError", {
+  /**
+   * `notAnEnvelope` — the magic prefix is absent, so these are raw bytes
+   * written before this format existed (or by something else entirely).
+   * `unsupportedVersion` — an envelope from a newer revision.
+   * `truncated` — the frame ends mid-header or mid-metadata.
+   * `metadataDecodeFailed` — the metadata is well-framed but does not satisfy
+   * the caller's schema. `metadataEncodeFailed` — the value being stored does
+   * not satisfy it.
+   */
+  readonly reason: Schema.Literals<readonly ["notAnEnvelope", "unsupportedVersion", "truncated", "metadataDecodeFailed", "metadataEncodeFailed"]>;
+  /** The envelope version found, when one was readable. */
+  readonly version: Schema.optionalKey<Schema.Number>;
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when bytes cannot be read as an envelope.
+ *
+ * @public
+ */
+declare class BlobEnvelopeError extends BlobEnvelopeError_base {
+  get message(): string;
+}
+/**
+ * The schema-versioned frame that gives a stored blob a **metadata channel**.
+ *
+ * @remarks
+ * Layout:
+ *
+ * ```text
+ * [4B magic "EFBS"][1B version][4B metadata length, big-endian][metadata JSON][body]
+ * ```
+ *
+ * Three properties earn the format, and each replaces something a consumer was
+ * hand-rolling:
+ *
+ * - **The magic prefix makes a legacy blob legible.** Raw, unframed bytes
+ *   decode as `notAnEnvelope` rather than as garbage metadata, so a store
+ *   holding pre-envelope entries produces a clean miss instead of a corrupt
+ *   read.
+ * - **The version lives in the blob, not in the key.** A consumer previously
+ *   namespaced keys (`v2/...`) to represent a format change, because there was
+ *   no in-band version. Here a revision is detected on read and reported
+ *   typed, so **keys stay stable** and old entries age out naturally.
+ * - **The metadata is the caller's own schema.** This module owns *framing*;
+ *   the caller owns *meaning*. Fields like a cache tag or a duration stop
+ *   being bytes at fixed offsets in a consumer's private codec.
+ *
+ * **Pure**: `Result`-returning, no IO, no service — the framing is testable
+ * from a byte array, which is the point.
+ *
+ * @public
+ */
+declare class BlobEnvelope {
+  private constructor();
+  /** The version this build writes. */
+  static readonly version: number;
+  /** Frame metadata and a body into a single blob. */
+  static encodeResult<A, I>(metadata: A, body: Uint8Array, schema: Schema.Codec<A, I>): Result.Result<Uint8Array, BlobEnvelopeError>;
+  /** Read a framed blob back into its metadata and body. */
+  static decodeResult<A, I>(bytes: Uint8Array, schema: Schema.Codec<A, I>): Result.Result<{
+    readonly metadata: A;
+    readonly body: Uint8Array;
+  }, BlobEnvelopeError>;
+}
+//#endregion
+//#region src/BlobStore.d.ts
+declare const BlobStoreError_base: Schema.Class<BlobStoreError, Schema.TaggedStruct<"BlobStoreError", {
+  /**
+   * `unreachable` — the store could not be contacted. `refused` — it answered,
+   * unhappily; `status` says how. `misconfigured` — the layer was built with
+   * settings the store cannot use.
+   */
+  readonly reason: Schema.Literals<readonly ["unreachable", "refused", "misconfigured"]>;
+  /** The key involved. A stable identifier, never a value. */
+  readonly key: Schema.optionalKey<Schema.String>;
+  /** The HTTP status, when the store answered. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** What is wrong, when the reason alone does not say. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a blob cannot be stored or retrieved.
+ *
+ * @public
+ */
+declare class BlobStoreError extends BlobStoreError_base {
+  get message(): string;
+}
+/**
+ * A stored value: the caller's metadata beside the bytes it describes.
+ *
+ * @public
+ */
+interface Blob<A> {
+  /** The caller's own metadata, decoded through the caller's own schema. */
+  readonly metadata: A;
+  /** The payload, verbatim. */
+  readonly body: Uint8Array;
+}
+/**
+ * The {@link BlobStore} service shape.
+ *
+ * @public
+ */
+interface BlobStoreShape {
+  /** Read a blob, or nothing if the key is absent. */
+  readonly get: <A, I>(key: string, schema: Schema.Codec<A, I>) => Effect.Effect<Option.Option<Blob<A>>, BlobStoreError | BlobEnvelopeError>;
+  /** Write a blob. */
+  readonly put: <A, I>(key: string, blob: Blob<A>, schema: Schema.Codec<A, I>) => Effect.Effect<void, BlobStoreError | BlobEnvelopeError>;
+  /** Whether a key is present, without transferring the body. */
+  readonly has: (key: string) => Effect.Effect<boolean, BlobStoreError>;
+}
+/**
+ * How to reach an S3-compatible object store.
+ *
+ * @public
+ */
+interface S3Config {
+  readonly bucket: string;
+  readonly region: string;
+  /**
+   * A custom endpoint, e.g. `https://<account>.r2.cloudflarestorage.com`.
+   *
+   * @remarks
+   * Omitting it targets AWS itself. Addressing is always **path-style**
+   * (`<endpoint>/<bucket>/<key>`), which is what makes the same layer work
+   * against R2, MinIO and Spaces — virtual-host addressing needs per-bucket
+   * DNS that none of them provide the same way.
+   */
+  readonly endpoint?: string | undefined;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: Redacted.Redacted<string>;
+  /** For temporary credentials. */
+  readonly sessionToken?: Redacted.Redacted<string> | undefined;
+  /** Prepended to every key, so one bucket can hold several caches. */
+  readonly prefix?: string | undefined;
+}
+declare const BlobStore_base: Context.ServiceClass<BlobStore, "@effected/github-actions/BlobStore", BlobStoreShape>;
+/**
+ * Durable blob storage with a metadata channel.
+ *
+ * @remarks
+ * `get`/`put`/`has` over `Uint8Array` **plus the caller's own metadata**, framed
+ * by {@link BlobEnvelope}. The metadata channel is the reason this exists: the
+ * consumer it was designed against hand-rolled a binary frame
+ * (`[4B tagLen][4B durationMs][tag][body]`) and namespaced its keys with a `v2`
+ * prefix to represent a format change. Both are framing concerns that had
+ * leaked into a consumer, and both are absorbed here.
+ *
+ * Deliberately no `list` and no `delete`: eviction belongs to the backend, both
+ * backends already have one, and no consumer asked for either.
+ *
+ * @example
+ * ```ts
+ * import { BlobStore } from "@effected/github-actions";
+ * import { Effect, Schema } from "effect";
+ *
+ * class Meta extends Schema.Class<Meta>("Meta")({ tag: Schema.String, durationMs: Schema.Number }) {}
+ *
+ * const program = Effect.gen(function* () {
+ *   const store = yield* BlobStore;
+ *   yield* store.put("build/1", { metadata: Meta.make({ tag: "x", durationMs: 12 }), body: bytes }, Meta);
+ *   return yield* store.get("build/1", Meta);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class BlobStore extends BlobStore_base {
+  /**
+   * An S3-compatible backend, signed with SigV4.
+   *
+   * @remarks
+   * No `@aws-sdk/*` dependency: signing is a specified algorithm over strings
+   * and HMACs, and this package already has `node:crypto`. The SDK's weight is
+   * in credential management, retries and a service catalogue none of which
+   * this needs.
+   *
+   * A parameterized layer factory mints a fresh layer per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  static readonly layerS3: (config: S3Config) => Layer.Layer<BlobStore, never, HttpClient.HttpClient | ActionOutputs>;
+  /** A test double. Unstubbed members die rather than reporting a miss. */
+  static readonly makeTest: (overrides?: Partial<BlobStoreShape>) => BlobStoreShape;
+  /** {@link BlobStore.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<BlobStoreShape>) => Layer.Layer<BlobStore>;
+  /**
+   * An in-memory backend.
+   *
+   * @remarks
+   * Not a stub: it runs the real {@link BlobEnvelope} framing, so a round trip
+   * through it exercises encode and decode exactly as a network backend would.
+   * A test that wants to prove its metadata survives storage should use this
+   * rather than a double whose `get` returns whatever its `put` was handed.
+   */
+  static readonly layerMemory: Layer.Layer<BlobStore>;
+}
+//#endregion
+//#region src/BlobStore.githubCache.d.ts
+/**
+ * The {@link BlobStore} backend that stores blobs in the runner's own Actions
+ * cache.
+ *
+ * @remarks
+ * The Actions cache is reachable over a Twirp v2 protocol at
+ * `ACTIONS_RESULTS_URL`, which answers a `CreateCacheEntry` /
+ * `GetCacheEntryDownloadURL` RPC with a **pre-signed Azure blob url** — which is
+ * why this backend lives in its own module rather than beside the S3 one, and
+ * why the spec's "Azure is confined to the cache and the artifact service" is
+ * three modules rather than two.
+ *
+ * **Only reachable from a `uses:` step.** The runner injects
+ * `ACTIONS_RESULTS_URL` and `ACTIONS_RUNTIME_TOKEN` into action execution
+ * contexts and not into `run:` shell steps, so a program that works when
+ * invoked from a bundled action fails as `misconfigured` when the same code is
+ * run by `node ./main.js` in a workflow step. The failure names the variable
+ * for exactly that reason.
+ *
+ * The layer statics live here rather than on {@link BlobStore} because a static
+ * belongs to the module that owns the dependency it needs: putting
+ * `BlobStore.layerGitHubCache` on the service class would make `@azure/storage-blob`
+ * reachable from every module that reads a blob.
+ *
+ * @example
+ * ```ts
+ * import { GitHubCacheBlobStore } from "@effected/github-actions";
+ *
+ * const layer = GitHubCacheBlobStore.layer;
+ * ```
+ *
+ * @public
+ */
+declare class GitHubCacheBlobStore {
+  private constructor();
+  /** The backend, over the real Azure client. */
+  static readonly layer: Layer.Layer<BlobStore, never, HttpClient.HttpClient | ActionEnvironment>;
+  /**
+   * The backend, over a supplied transport.
+   *
+   * @remarks
+   * The Twirp protocol — the RPC sequence, the conflict handling, the retry
+   * policy, the framing — is what this package owns and what a test needs to
+   * exercise; the Azure client is a pre-signed `PUT` that owns none of it. This
+   * is also the seam an integration test uses to point the same protocol at a
+   * local blob endpoint.
+   *
+   * A parameterized layer factory mints a fresh layer per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  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", {
+  /**
+   * `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};
+   * see there for why this is the most important value in the module.
+   * `signalFailed` — the signal was refused, e.g. the process belongs to
+   * another user. `notReady` — the readiness probe never held.
+   */
+  readonly reason: Schema.Literals<readonly ["logUnavailable", "spawnFailed", "invalidPid", "signalFailed", "notReady"]>;
+  /** The pid involved, when one is. */
+  readonly pid: Schema.optionalKey<Schema.Number>;
+  /** The path involved, when one is. */
+  readonly path: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a detached child cannot be started, waited for, or reaped.
+ *
+ * @public
+ */
+declare class DetachedProcessError extends DetachedProcessError_base {
+  get message(): string;
+}
+/**
+ * The schema a pid crosses the phase boundary through.
+ *
+ * @remarks
+ * A pid is persisted in `GITHUB_STATE` by `main` and read back by `post`, which
+ * means it makes the round trip as **text**. This is the boundary check on the
+ * way back in: a truncated file, an absent key or a `Number("")` all decode to
+ * `0`, and `0` is not a process — it is the current process's whole group.
+ * Refusing it here means the bad value never reaches {@link DetachedProcess.reap}
+ * in the first place, and reap's own guard is the second of two defenses rather
+ * than the only one.
+ *
+ * **The brand is core's**, from `ChildProcessSpawner` — the subprocess
+ * vocabulary belongs to core and this package does not get to re-declare it.
+ * What core does not have is a *validating* way to reconstruct one: its
+ * constructor is `Brand.nominal`, which applies no runtime check, so
+ * `ChildProcessSpawner.ProcessId(0)` succeeds. That is exactly right for a pid
+ * the spawner just produced, and exactly wrong for a pid that has been through a
+ * text file. This schema is that missing check, and it decodes to core's type so
+ * the two are interchangeable.
+ *
+ * @example
+ * ```ts
+ * import { ActionState, DetachedProcess, ProcessId } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const post = Effect.gen(function* () {
+ *   const pid = yield* (yield* ActionState).get("server-pid", ProcessId);
+ *   return yield* DetachedProcess.reap(pid);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const ProcessId: Schema.brand<Schema.Number, "ProcessId">;
+/**
+ * How a detached child is started.
+ *
+ * @public
+ */
+interface DetachedSpawnOptions {
+  /** The executable. */
+  readonly command: string;
+  /** Its arguments. */
+  readonly args?: ReadonlyArray<string> | undefined;
+  /**
+   * Where the child's stdout and stderr go, opened for append.
+   *
+   * @remarks
+   * A file **descriptor**, not a pipe. An in-process pipe would keep the parent
+   * attached to the child and defeat the detachment, which is the upstream
+   * limitation this module exists to work around — core's `CommandOptions.stdout`
+   * maps to a pipe, and so do its additional fds. If core grows fd routing this
+   * becomes a thin adapter over it.
+   */
+  readonly logFile: string;
+  /** The working directory. */
+  readonly cwd?: string | undefined;
+  /**
+   * Environment additions.
+   *
+   * @remarks
+   * **Merged over the parent's environment, not substituted for it.** A bare
+   * environment costs the child `PATH`, which usually means it cannot find its
+   * own runtime and dies before writing a word to the log — a failure that
+   * looks like a spawn bug and is not. Secrets belong here only via
+   * `Secret.forChildEnv`, which masks them on the way out.
+   */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * How long to wait for a child to become ready.
+ *
+ * @public
+ */
+interface ReadinessOptions {
+  /** Time between probes. Defaults to 150 milliseconds. */
+  readonly interval?: Duration.Input | undefined;
+  /** How many times to retry after the first probe. Defaults to 40. */
+  readonly attempts?: number | undefined;
+}
+/**
+ * A long-lived child that outlives the phase that started it.
+ *
+ * @remarks
+ * The shape an action needs is three separate things, because the child
+ * survives the process that spawned it: `main` starts it and persists the pid,
+ * `main` or `post` waits on a domain predicate rather than on time, and `post`
+ * — a **different process**, holding no handle to the child — signals the pid
+ * it read back out of `GITHUB_STATE`.
+ *
+ * That last step is why this lives here rather than in a command runner. There
+ * is no `ChildProcess` to `.kill()`; there is only a number that has been
+ * through a text file. See {@link DetachedProcess.reap}.
+ *
+ * @example
+ * ```ts
+ * import { DetachedProcess } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pid = yield* DetachedProcess.spawn({
+ *     command: "node",
+ *     args: ["server.js"],
+ *     logFile: "/tmp/server.log",
+ *   });
+ *   yield* DetachedProcess.awaitReady(healthCheck);
+ *   return pid;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class DetachedProcess {
+  private constructor();
+  /**
+   * Start a detached child with its output routed to a log file.
+   *
+   * @remarks
+   * The parent closes its own copy of the descriptor immediately — the child
+   * holds a duplicate, so the log keeps filling after the action's process
+   * exits, which is the entire point.
+   */
+  static readonly spawn: (options: DetachedSpawnOptions) => Effect.Effect<ChildProcessSpawner.ProcessId, DetachedProcessError, never>;
+  /**
+   * Poll a predicate until it holds.
+   *
+   * @remarks
+   * A domain predicate rather than a sleep: "the server answers" is the thing
+   * being waited for, and any fixed delay is simultaneously too long on a fast
+   * runner and too short on a slow one. Two consumers hand-rolled this, one of
+   * them around an `Effect.suspend` footgun it had to explain in a comment.
+   *
+   * A probe *failure* is propagated rather than treated as "not ready" — a
+   * probe that cannot run is a different situation from a child that is not up
+   * yet, and silently retrying the first is how a misconfigured probe becomes a
+   * timeout six seconds later with nothing to show for it.
+   */
+  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<void, E | DetachedProcessError, R>;
+  /**
+   * Signal a pid that came back across the phase boundary.
+   *
+   * @remarks
+   * **The guard is the reason this function exists.** `process.kill(0, …)`
+   * signals the caller's entire process group and `process.kill(-1, …)` signals
+   * every process the user owns — so on a GitHub runner, an unguarded reap of a
+   * pid that decoded to `0` takes down the job that is running it. The value is
+   * exactly the one most likely to be wrong: it is what an absent state key, a
+   * truncated state file or a `Number("")` all produce.
+   *
+   * A non-positive pid therefore fails **typed and before any signal is sent**.
+   * The parameter is a plain `number` rather than a {@link ProcessId} on purpose:
+   * the value arrives as text from another process, so the type system stopped
+   * applying the moment it crossed that boundary, and a guard that only a
+   * well-typed caller can trip is not a guard.
+   *
+   * Returns `false` for a process that is already gone, because a `post` phase
+   * finding its child already dead is the normal ending, not a failure.
+   */
+  static readonly reap: (pid: number, signal?: NodeJS.Signals | undefined) => Effect.Effect<boolean, DetachedProcessError, never>;
+}
+//#endregion
+//#region src/DryRun.d.ts
+/**
+ * The {@link DryRun} service shape.
+ *
+ * @public
+ */
+interface DryRunShape {
+  /** Whether this run is a rehearsal. */
+  readonly isDryRun: Effect.Effect<boolean>;
+  /**
+   * Run a mutation, or skip it and take the fallback.
+   *
+   * @remarks
+   * The `label` is what a dry run reports instead of doing the work, so it
+   * should name the mutation from the workflow author's point of view
+   * (`"publish @acme/thing@1.2.3"`), not the function that would have run it.
+   *
+   * The fallback is required rather than optional on purpose: a mutation whose
+   * result the caller uses must say what a rehearsal produces instead, and the
+   * type is the place to force that. For a `void` mutation it is simply
+   * `undefined`.
+   */
+  readonly guard: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>, fallback: A) => Effect.Effect<A, E, R>;
+}
+declare const DryRun_base: Context.ServiceClass<DryRun, "@effected/github-actions/DryRun", DryRunShape>;
+/**
+ * The rehearsal guard: every mutation an action performs goes through it, so a
+ * workflow can be run end to end without changing anything.
+ *
+ * @remarks
+ * A service rather than a boolean threaded through call sites, because the
+ * decision has to be available wherever a mutation is, and because a test that
+ * wants to prove "this path mutates nothing" provides one layer instead of
+ * auditing every branch.
+ *
+ * @example
+ * ```ts
+ * import { DryRun } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const dryRun = yield* DryRun;
+ *   yield* dryRun.guard("publish @acme/thing@1.2.3", publish, undefined);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class DryRun extends DryRun_base {
+  /**
+   * Driven by the `dry-run` action input, defaulting to a real run.
+   *
+   * @remarks
+   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
+   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
+   * not quietly perform the mutations it meant to rehearse.
+   */
+  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
+  /**
+   * Driven by a named input.
+   *
+   * @remarks
+   * A parameterized layer factory mints a fresh layer per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  static readonly layerFromInput: (name: string) => Layer.Layer<DryRun, Config.ConfigError>;
+  /** Driven by an explicit decision the caller has already made. */
+  static readonly layerFrom: (enabled: boolean) => Layer.Layer<DryRun>;
+  /**
+   * A double that rehearses.
+   *
+   * @remarks
+   * **A recorded exception to the die-on-unstubbed rule.** The default is not a
+   * fabrication but the safe direction: a test that forgot to say which mode it
+   * wants gets the mode that mutates nothing. The members are the real
+   * implementation, so the double cannot drift from it.
+   */
+  static readonly makeTest: (overrides?: Partial<DryRunShape>) => DryRunShape;
+  /** {@link DryRun.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<DryRunShape>) => Layer.Layer<DryRun>;
+}
+//#endregion
+//#region src/GitHubToken.d.ts
+declare const GitHubTokenError_base: Schema.Class<GitHubTokenError, Schema.TaggedStruct<"GitHubTokenError", {
+  /**
+   * One reason, deliberately: everything else that can go wrong here already
+   * has an owner — persistence is an `ActionStateError`, minting is a
+   * `GitHubAppError`, and scope verification is a `TokenPermissionError`.
+   */
+  readonly reason: Schema.Literals<readonly ["expired"]>;
+  /** When GitHub stopped accepting it, ISO-8601. */
+  readonly expiresAt: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the token an earlier phase persisted cannot be used.
+ *
+ * @public
+ */
+declare class GitHubTokenError extends GitHubTokenError_base {
+  get message(): string;
+}
+/**
+ * What to mint a token for.
+ *
+ * @public
+ */
+interface ProvisionOptions {
+  /** The app id or client id. */
+  readonly appId: string;
+  /** The app's private key, in PEM. */
+  readonly privateKey: Redacted.Redacted<string>;
+  /** The installation. Discovered from `owner`, or from the app's only installation, when omitted. */
+  readonly installationId?: number | undefined;
+  /** The account whose installation to use, when `installationId` is omitted. */
+  readonly owner?: string | undefined;
+  /**
+   * The permissions the action needs.
+   *
+   * @remarks
+   * Verified against what GitHub actually granted, which can be narrower than
+   * what was asked for. Checked **before** the token is persisted, so a
+   * workflow with a misconfigured installation fails at `pre` with a message
+   * naming the missing permission rather than in the middle of `main` with a
+   * `403` on one request.
+   */
+  readonly required?: Readonly<Record<string, PermissionLevel>> | undefined;
+  /** The `GITHUB_STATE` key. One default, so `pre` and `post` agree without saying so. */
+  readonly stateKey?: string | undefined;
+}
+/** Where to read a persisted token from. @public */
+interface ReadOptions {
+  /** The `GITHUB_STATE` key. */
+  readonly stateKey?: string | undefined;
+  /**
+   * How long before the stated expiry to treat the token as spent.
+   *
+   * @remarks
+   * A minute by default. The window exists because the check and the request
+   * it guards are not the same instant.
+   */
+  readonly skew?: Duration.Duration | undefined;
+}
+/** How to build a client from a persisted token. @public */
+interface ClientLayerOptions extends ReadOptions {
+  /** Retry behavior. Defaults to the client's own policy; `"off"` disables it. */
+  readonly retry?: RetryPolicy | "off" | undefined;
+  /** A GitHub Enterprise API root. */
+  readonly baseUrl?: string | undefined;
+  /** Appended to octokit's own user agent. */
+  readonly userAgent?: string | undefined;
+  /** A replacement for the global `fetch`. */
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}
+/**
+ * The GitHub App token lifecycle, shaped like a workflow.
+ *
+ * @remarks
+ * One of the two seams between this package and
+ * [`@effected/github`](https://npmjs.com) — mint in `pre`, use in `main`,
+ * revoke in `post`. The three phases are **three separate processes**, so
+ * nothing survives between them except what `GITHUB_STATE` carries, which is
+ * why this is a persistence problem rather than a `Scope`.
+ *
+ * That is also why `GitHubApp.scopedToken` is the wrong primitive here and
+ * `GitHubApp.clientLayer` is a different thing entirely: both revoke when their
+ * scope closes, and the scope closes at the end of `pre` — before `main` has
+ * run a single request.
+ *
+ * **The token lives about an hour, and no later phase can re-mint one.** The
+ * credentials that could are the app's private key, and persisting *that*
+ * through `GITHUB_STATE` — a plaintext file by GitHub's protocol — would trade
+ * a one-hour token for a permanent one. So the v1 contract is stated rather
+ * than worked around: {@link GitHubToken.read} fails typed when the persisted
+ * token is spent, and a phase that can outlive the hour calls
+ * {@link GitHubToken.provision} itself.
+ *
+ * Grouped statics on one module reaching one dependency — the carve-out to the
+ * no-namespace-objects rule, not the hazard it names. Every member's `R` says
+ * exactly which services it needs, and the members below say which parts of
+ * each they touch, so a partial double is built from the documentation rather
+ * than from a stack trace:
+ *
+ * | Member | `ActionState` | `ActionOutputs` | `GitHubApp` |
+ * | --- | --- | --- | --- |
+ * | `provision` | `save` | `setSecret` | `token`, `identity`, `revoke` |
+ * | `read` | `get` | — | — |
+ * | `botIdentity` | `get` | — | — |
+ * | `clientLayer` | `get` | — | — |
+ * | `dispose` | `getOptional` | — | `revoke` |
+ *
+ * @example
+ * ```ts
+ * import { GitHubToken } from "@effected/github-actions";
+ * import { Effect, Redacted } from "effect";
+ *
+ * const pre = Effect.gen(function* () {
+ *   return yield* GitHubToken.provision({
+ *     appId: "123456",
+ *     privateKey: Redacted.make(pem),
+ *     owner: "acme",
+ *     required: { contents: "write", pull_requests: "write" },
+ *   });
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class GitHubToken {
+  private constructor();
+  /**
+   * Mint a token, verify its scopes, mask it and persist it for later phases.
+   *
+   * @remarks
+   * An `acquireUseRelease`, and the release arm is the load-bearing part: if
+   * scope verification or persistence fails, the minted token is **revoked**
+   * rather than left live until GitHub expires it. A workflow that retries a
+   * failing `pre` would otherwise leave an hour's worth of unreferenced write
+   * tokens behind, each of which is a credential nobody is tracking.
+   *
+   * The masking happens **before** the persistence, through
+   * {@link Secret.forRunnerFile}, so the ordering is structural rather than
+   * remembered: `GITHUB_STATE` is plaintext by protocol, and the runner's log
+   * filter is the only defense available.
+   */
+  static readonly provision: (options: ProvisionOptions) => Effect.Effect<InstallationToken, ActionStateError | import("@effected/github").GitHubAppError | import("@effected/github").TokenPermissionError, ActionOutputs | ActionState | GitHubApp>;
+  /**
+   * The token an earlier phase persisted.
+   *
+   * @remarks
+   * Fails typed when it is spent. The package this replaces persisted the
+   * expiry and read it nowhere, so a `main` phase that outlived the hour simply
+   * started answering `401` with no explanation — which is the single hardest
+   * failure in this whole lifecycle to diagnose from a workflow log.
+   */
+  static readonly read: (options?: ReadOptions | undefined) => Effect.Effect<InstallationToken, ActionStateError | GitHubTokenError, ActionState>;
+  /**
+   * The committer identity a commit made with the persisted token should carry.
+   *
+   * @remarks
+   * Pure once the token is in hand — the identity fields travel with it — so
+   * this costs one state read and no request.
+   */
+  static readonly botIdentity: (options?: ReadOptions | undefined) => Effect.Effect<BotIdentity, ActionStateError | GitHubTokenError, ActionState>;
+  /**
+   * A client built from the persisted token.
+   *
+   * @remarks
+   * Built with `GitHubClient.layerFromToken` rather than through `GitHubApp`,
+   * and the difference matters: the App path links a JWT signer and needs the
+   * private key, neither of which a later phase has or should have. This path
+   * needs only the token the `pre` phase already minted.
+   *
+   * A parameterized layer factory mints a fresh layer per call and layers
+   * memoize by reference — bind it to a `const` rather than calling it at each
+   * composition site.
+   */
+  static readonly clientLayer: (options?: ClientLayerOptions) => Layer.Layer<GitHubClient, ActionStateError | GitHubTokenError, ActionState>;
+  /**
+   * Revoke the persisted token, if there is one.
+   *
+   * @remarks
+   * `getOptional`, so a `post` phase that runs after a `pre` that never got as
+   * far as provisioning is a **no-op rather than a failure** — which is the
+   * common shape of a workflow that failed early, and the last thing it needs
+   * is a second failure on the way out.
+   *
+   * An already-expired token is not revoked either: GitHub has already stopped
+   * accepting it, so the request would fail and the only thing it could
+   * accomplish is turning a successful run into a failed one.
+   */
+  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>;
+}>, 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/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.
+   */
+  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.
+   *
+   * 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.
+   */
+  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
+//#region src/ToolInstaller.d.ts
+declare const ToolInstallerError_base: Schema.Class<ToolInstallerError, Schema.TaggedStruct<"ToolInstallerError", {
+  /**
+   * `downloadFailed` — the archive could not be fetched. `extractFailed` — the
+   * extraction tool refused the archive or is not installed. `cacheFailed` —
+   * the tool could not be written into the runner's tool cache.
+   */
+  readonly reason: Schema.Literals<readonly ["downloadFailed", "extractFailed", "cacheFailed"]>;
+  /** The HTTP status, when there was one. Drives the retry decision. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** What was being worked on — a url, an archive path, or a tool name. */
+  readonly subject: Schema.optionalKey<Schema.String>;
+  /** The extraction tool's own complaint, which is the only useful part of a tar failure. */
+  readonly stderr: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a tool cannot be downloaded, extracted or cached.
+ *
+ * @public
+ */
+declare class ToolInstallerError extends ToolInstallerError_base {
+  get message(): string;
+  /**
+   * Whether retrying could plausibly help.
+   *
+   * @remarks
+   * A derived getter rather than a field, so it cannot be set inconsistently
+   * with the status it is derived from. `408`, `429` and any `5xx` are the
+   * server saying "later"; a `404` is it saying "never", and retrying that
+   * three times just makes a broken url take longer to fail.
+   */
+  get retryable(): boolean;
+}
+/**
+ * Where extraction should put its output.
+ *
+ * @public
+ */
+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. */
+  readonly flags?: ReadonlyArray<string> | undefined;
+}
+/**
+ * The {@link ToolInstaller} service shape.
+ *
+ * @public
+ */
+interface ToolInstallerShape {
+  /**
+   * A cached tool, if this runner already has it.
+   *
+   * @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.
+   */
+  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>;
+  /** 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. */
+  readonly extractZip: (archive: string, options?: ExtractOptions) => Effect.Effect<string, ToolInstallerError>;
+  /** Install a directory into the tool cache. Returns its cached path. */
+  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>;
+}
+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).
+ *
+ * No `@actions/tool-cache` dependency — the cache is a directory layout, and
+ * this reproduces the layout rather than importing a package to compute it.
+ *
+ * @example
+ * ```ts
+ * import { ToolInstaller } from "@effected/github-actions";
+ * import { Effect, Option } from "effect";
+ *
+ * const install = Effect.gen(function* () {
+ *   const installer = yield* ToolInstaller;
+ *   const cached = yield* installer.find("node", "22.11.0");
+ *   if (Option.isSome(cached)) return cached.value;
+ *   const archive = yield* installer.download("https://nodejs.org/dist/v22.11.0/node.tar.gz");
+ *   const extracted = yield* installer.extractTar(archive);
+ *   return yield* installer.cacheDir(extracted, "node", "22.11.0");
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ToolInstaller extends ToolInstaller_base {
+  static readonly layer: Layer.Layer<ToolInstaller, never, ActionEnvironment | FileSystem.FileSystem | Path.Path | HttpClient.HttpClient | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * Where a tool lives in the cache.
+   *
+   * @remarks
+   * Pure, exported and tested on its own, because the layout is a **contract
+   * with the runner**: `<root>/<tool>/<version>/<arch>` is what the hosted
+   * image populates and what `@actions/tool-cache` reads, so a tool cached at
+   * any other path is invisible to every other step in the workflow. The `arch`
+   * segment uses Node's `process.arch` spelling (`x64`) rather than the
+   * runner's `RUNNER_ARCH` (`X64`) for the same reason.
+   */
+  static readonly cachePath: (options: {
+    readonly root: string;
+    readonly tool: string;
+    readonly version: string;
+    readonly arch: string;
+  }) => string;
+  /** A test double. Unstubbed members die rather than reporting a tool that is not there. */
+  static readonly makeTest: (overrides?: Partial<ToolInstallerShape>) => ToolInstallerShape;
+  /** {@link ToolInstaller.makeTest} behind `Layer.succeed`. */
+  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 };
+//# sourceMappingURL=index.d.ts.map