@effected/github-actions 0.19.0 → 0.20.0

package/index.d.ts

@@ -1,3 +1,4 @@
+import { AnnotationProperties, AnnotationProperties as AnnotationProperties$1, WorkflowCommand } from "@effected/github-commands";
 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/http";
@@ -7,6 +8,7 @@ import { BotIdentity, GitHubApp, GitHubClient, InstallationToken, PermissionLeve
 import { IntegrityHashBrand, PackageManagerPin } from "@effected/npm";
 //#region src/ActionEnvironment.d.ts
 declare const ActionEnvironmentError_base: Schema.Class<ActionEnvironmentError, Schema.TaggedStruct<"ActionEnvironmentError", {
+  /** `missing` — absent or empty; `malformed` — present but unusable. */
   readonly reason: Schema.Literals<readonly ["missing", "malformed"]>;
   /** The environment variable involved. */
   readonly name: Schema.String;
@@ -31,6 +33,7 @@ export declare class ActionEnvironmentError extends ActionEnvironmentError_base
 declare const GitHubContext_base: Schema.Class<GitHubContext, Schema.Struct<{
   /** `owner/repo`. */
   readonly repository: Schema.String;
+  /** The repository owner's login. */
   readonly repositoryOwner: Schema.String;
   /** The full ref, e.g. `refs/heads/main`. */
   readonly ref: Schema.String;
@@ -52,16 +55,27 @@ declare const GitHubContext_base: Schema.Class<GitHubContext, Schema.Struct<{
    * an encoded context stays plain JSON.
    */
   readonly headRef: Schema.OptionFromNullOr<Schema.String>;
+  /** The commit SHA that triggered the workflow. */
   readonly sha: Schema.String;
+  /** The workflow's name. */
   readonly workflow: Schema.String;
+  /** The current job's id. */
   readonly job: Schema.String;
+  /** The run's unique number, decoded from `GITHUB_RUN_ID`. */
   readonly runId: Schema.Number;
+  /** The attempt number of this run, starting at 1. */
   readonly runAttempt: Schema.Number;
+  /** The name of the event that triggered the workflow, e.g. `push`. */
   readonly eventName: Schema.String;
+  /** The login of the user that triggered the run. */
   readonly actor: Schema.String;
+  /** The GitHub server URL, e.g. `https://github.com`. */
   readonly serverUrl: Schema.String;
+  /** The REST API URL, e.g. `https://api.github.com`. */
   readonly apiUrl: Schema.String;
+  /** The GraphQL API URL. */
   readonly graphqlUrl: Schema.String;
+  /** The default working directory on the runner for steps. */
   readonly workspace: Schema.String;
 }>, {}>;
 /**
@@ -84,8 +98,11 @@ export declare class GitHubContext extends GitHubContext_base {
   get branch(): string;
 }
 declare const RunnerContext_base: Schema.Class<RunnerContext, Schema.Struct<{
+  /** The runner's operating system: `Linux`, `Windows` or `macOS`. */
   readonly os: Schema.String;
+  /** The runner's architecture, e.g. `X64` or `ARM64`. */
   readonly arch: Schema.String;
+  /** The runner's name. */
   readonly name: Schema.String;
   /** A scratch directory emptied between jobs. */
   readonly temp: Schema.String;
@@ -99,7 +116,8 @@ declare const RunnerContext_base: Schema.Class<RunnerContext, Schema.Struct<{
  */
 export declare class RunnerContext extends RunnerContext_base {}
 /**
- * The {@link ActionEnvironment} service shape.
+ * The members of the {@link ActionEnvironment} service: variable lookup, the
+ * `GITHUB_*` and `RUNNER_*` contexts, the event payload and scoped overrides.
  *
  * @public
  */
@@ -179,10 +197,10 @@ export declare class ActionEnvironment extends ActionEnvironment_base {
    * @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.
+   * a plausible default hides a real gap. Here the opposite is true: the context
+   * variables have one obviously-correct shape, and requiring each suite to
+   * restate them would duplicate a byte-identical block in every suite.
+   * Overrides merge on top.
    *
    * The optional second argument serves {@link ActionEnvironmentShape.payload}
    * **directly**, replacing the `GITHUB_EVENT_PATH` read rather than seeding a
@@ -242,84 +260,6 @@ export declare class ActionEnvironment extends ActionEnvironment_base {
   static readonly layerTest: (overrides?: Readonly<Record<string, string>>, payload?: unknown) => 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
- */
-export 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
 /**
  * Options for {@link ActionLoggerShape.withBuffer}.
@@ -355,7 +295,8 @@ interface WithStepOptions {
   readonly summary?: string;
 }
 /**
- * The {@link ActionLogger} service shape.
+ * The members of the {@link ActionLogger} service: log groups, buffered steps,
+ * notices and source annotations.
  *
  * @public
  */
@@ -408,10 +349,9 @@ interface ActionLoggerShape {
    * test.
    *
    * The header and the summary are the whole difference from `withBuffer`, and
-   * they are why this is a member rather than a documented recipe: the recipe
-   * was independently derived wrong three times by careful readers during one
-   * port, because `group` + `withBuffer` looks like complete parity until you
-   * notice nothing emits the success line.
+   * they are why this is a member rather than a documented recipe: `group` +
+   * `withBuffer` looks like complete parity until you notice nothing emits the
+   * success line.
    *
    * The summary survives step debugging. Buffering is skipped when the runner
    * asks for verbose output, but the line naming what succeeded is still the
@@ -425,16 +365,16 @@ interface ActionLoggerShape {
    * 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>;
+  readonly notice: (message: string, properties?: AnnotationProperties$1) => 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
+   * as `AnnotationProperties` (from `@effected/github-commands`) 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>;
+  readonly annotated: <A, E, R>(properties: AnnotationProperties$1, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
 }
 declare const ActionLogger_base: Context.ServiceClass<ActionLogger, "@effected/github-actions/ActionLogger", ActionLoggerShape>;
 /**
@@ -461,6 +401,14 @@ declare const ActionLogger_base: Context.ServiceClass<ActionLogger, "@effected/g
  * @public
  */
 export declare class ActionLogger extends ActionLogger_base {
+  /**
+   * The service: groups, the buffered step renderer, notices and annotations.
+   *
+   * @remarks
+   * This installs no `Logger`. Without {@link ActionLogger.layerLogger} (or `Action.run`, which installs it) Effect's
+   * default logger writes `Effect.log*` text raw, so a message carrying `::add-mask::` or `##[` is a workflow command
+   * to the runner. Install both: the service for its structure, the logger for its neutralizing of every log line.
+   */
   static readonly layer: Layer.Layer<ActionLogger, never, ActionEnvironment>;
   /**
    * The `Logger` that maps Effect log levels onto workflow commands.
@@ -474,7 +422,13 @@ export declare class ActionLogger extends ActionLogger_base {
    * observable in a test without a runner.
    */
   static readonly logger: Logger.Logger<unknown, void>;
-  /** {@link ActionLogger.logger} installed as the only logger. */
+  /**
+   * {@link ActionLogger.logger} installed as the only logger.
+   *
+   * @remarks
+   * Bound to a constant so every composition site shares one layer;
+   * `ActionRuntime.layer` already includes it.
+   */
   static readonly layerLogger: Layer.Layer<never>;
   /**
    * A silent double.
@@ -493,10 +447,9 @@ export declare class ActionLogger extends ActionLogger_base {
    * 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.
+   * This one layer stands in for a bare `Effect.provide(Logger.layer([]))`
+   * repeated in every suite just 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>;
 }
@@ -630,7 +583,9 @@ interface RecordingOutputs {
   readonly entries: () => ReadonlyArray<RecordedOutput>;
 }
 /**
- * The {@link ActionOutputs} service shape.
+ * The members of the {@link ActionOutputs} service: step outputs, exported
+ * variables, `PATH` additions, the job summary, masking and failure
+ * annotations.
  *
  * @public
  */
@@ -674,9 +629,30 @@ declare const ActionOutputs_base: Context.ServiceClass<ActionOutputs, "@effected
  * — 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.
  *
+ * Members that write a runner file fail with {@link ActionOutputError}.
+ *
+ * @example
+ * ```ts
+ * import { ActionOutputs } from "@effected/github-actions";
+ * import { Effect, Schema } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const outputs = yield* ActionOutputs;
+ *   yield* outputs.set("version", "1.2.3");
+ *   yield* outputs.setJson("packages", ["a", "b"], Schema.Array(Schema.String));
+ * });
+ * ```
+ *
  * @public
  */
 export declare class ActionOutputs extends ActionOutputs_base {
+  /**
+   * The live service, appending to the runner's `GITHUB_OUTPUT`, `GITHUB_ENV`,
+   * `GITHUB_PATH` and `GITHUB_STEP_SUMMARY` files.
+   *
+   * @remarks
+   * `ActionRuntime.layer` already provides every requirement.
+   */
   static readonly layer: Layer.Layer<ActionOutputs, never, ActionEnvironment | FileSystem.FileSystem>;
   /**
    * The outputs surface that is correct inside a **detached worker**.
@@ -686,10 +662,8 @@ export declare class ActionOutputs extends ActionOutputs_base {
    * stdout is a **log file no runner parses**, so under the real layer
    * `setSecret` emits `::add-mask::<plaintext>` into that file — a command
    * that is simultaneously **inert** (nothing reads it, so nothing is masked)
-   * and a **secret leak** (the plaintext is now sitting verbatim in a log). A
-   * production action shipped exactly that for one round: an S3 secret and
-   * session token written into a worker's log by the masking call itself.
-   * This layer is the worker-side fix; the parent-side rule is that every
+   * and a **secret leak** (the plaintext is now sitting verbatim in a log).
+   * This layer is the worker-side guard; the parent-side rule is that every
    * secret a worker will hold is masked **before** the spawn, by
    * `Secret.forChildEnv` under the real layer.
    *
@@ -702,7 +676,7 @@ export declare class ActionOutputs extends ActionOutputs_base {
    *   spelling of it in the log IS the leak. Masking is the parent's job,
    *   before the worker exists.
    * - **`set`, `setJson`, `exportVariable`, `addPath`, `summary` — fail
-   *   typed** (`reason: "detached"`, naming the file). Each writes a runner
+   *   typed** with {@link DetachedOutputError}, naming the file. Each writes a runner
    *   file that configures the parent job's *later steps* — `GITHUB_OUTPUT`,
    *   `GITHUB_ENV`, `GITHUB_PATH` — or is collected when the step completes
    *   (`GITHUB_STEP_SUMMARY`). A detached worker has no later steps, may
@@ -742,7 +716,7 @@ export declare class ActionOutputs extends ActionOutputs_base {
    * @remarks
    * This is the double most tests of an action want — "what did it publish?"
    * — shipped so that nobody hand-writes a `setJson` override that drops the
-   * schema encode (the trap `makeTest` now closes too). `setJson` encodes
+   * schema encode (a trap `makeTest` closes too). `setJson` encodes
    * through its schema exactly as the real layer does, failing typed with
    * {@link OutputEncodeError} and recording nothing on a drift, and records
    * the **encoded JSON text** — what the runner would have read — not the
@@ -774,11 +748,14 @@ declare const ActionStateError_base: Schema.Class<ActionStateError, Schema.Tagge
    * appended to.
    */
   readonly reason: Schema.Literals<readonly ["missing", "malformed", "notPlainJson", "writeFailed"]>;
+  /** The state key that was being saved or read. */
   readonly key: Schema.String;
+  /** The underlying failure, preserved structurally. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Raised when state cannot cross the phase boundary.
+ * Raised when action state cannot be saved, read or decoded across the phase
+ * boundary.
  *
  * @public
  */
@@ -786,7 +763,8 @@ export declare class ActionStateError extends ActionStateError_base {
   get message(): string;
 }
 /**
- * The {@link ActionState} service shape.
+ * The members of the {@link ActionState} service: save and read values, and
+ * persist secrets, across the `pre` → `main` → `post` boundary.
  *
  * @public
  */
@@ -833,11 +811,37 @@ declare const ActionState_base: Context.ServiceClass<ActionState, "@effected/git
  * 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.
+ * pair of helpers. Every member fails with {@link ActionStateError}.
+ *
+ * @example
+ * ```ts
+ * import { ActionState } from "@effected/github-actions";
+ * import { Effect, Schema } from "effect";
+ *
+ * // in `pre`
+ * const pre = Effect.gen(function* () {
+ *   const state = yield* ActionState;
+ *   yield* state.save("server-pid", 4242, Schema.Number);
+ * });
+ *
+ * // in `post`
+ * const post = Effect.gen(function* () {
+ *   const state = yield* ActionState;
+ *   const pid = yield* state.get("server-pid", Schema.Number);
+ *   return pid;
+ * });
+ * ```
  *
  * @public
  */
 export declare class ActionState extends ActionState_base {
+  /**
+   * The live service, writing to the runner's `GITHUB_STATE` file and reading
+   * the `STATE_<key>` variables it republishes.
+   *
+   * @remarks
+   * `ActionRuntime.layer` already provides every requirement.
+   */
   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;
@@ -924,7 +928,7 @@ interface ActionRunOptions<R> {
  * 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
+ * `[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.
@@ -955,11 +959,11 @@ export declare const describeCause: (cause: Cause.Cause<unknown>) => string;
  *
  * 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 wrap the program in a log buffer.** A buffer that swallowed
+ *   the transcript on an unhandled defect would leave a run that 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
@@ -968,9 +972,9 @@ export declare const describeCause: (cause: Cause.Cause<unknown>) => string;
  * 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`.
+ * only when someone turns step debugging on. No JS stack is spliced into the
+ * visible error, because in a bundled action it points at one line of
+ * `dist/main.js`.
  *
  * @example
  * ```ts
@@ -989,8 +993,9 @@ export declare class Action {
    * Run an action program to completion.
    *
    * @remarks
-   * Resolves whether the program succeeded or not; read `process.exitCode` for
-   * the verdict.
+   * Never rejects: the promise resolves whether the program succeeded or not,
+   * so read `process.exitCode` for the verdict. Requirements beyond
+   * {@link ActionServices} come from `options.layer`.
    */
   static readonly run: <E, R = never>(program: Effect.Effect<void, E, ActionServices | R>, options?: ActionRunOptions<R>) => Promise<void>;
 }
@@ -1191,13 +1196,12 @@ export declare class CacheKey extends CacheKey_base {
    * A copy of this key that restores from its **exact key only** — no ladder.
    *
    * @remarks
-   * The third point in the policy space, and the one the typed key had no
-   * spelling for: absence of a policy means the default every-prefix ladder,
-   * so exact-match-only restores (a cache-bust mode, where a stale partial
-   * hit is worse than a cold start) previously forced the caller back to the
-   * string form. This is the same `restoreDepths` field carrying **zero
-   * rungs** — an honest value, not a sentinel: `ActionCache.restore` sends no
-   * `restore_keys` at all, so the backend answers this key or a miss.
+   * The third point in the policy space: absence of a policy means the default
+   * every-prefix ladder, so exact-match-only restores (a cache-bust mode, where
+   * a stale partial hit is worse than a cold start) need their own spelling.
+   * This is the same `restoreDepths` field carrying **zero rungs** — an honest
+   * value, not a sentinel: `ActionCache.restore` sends no `restore_keys` at
+   * all, so the backend answers this key or a miss.
    *
    * @example
    * ```ts
@@ -1437,7 +1441,8 @@ export declare class ActionCacheError extends ActionCacheError_base {
   get message(): string;
 }
 /**
- * The {@link ActionCache} service shape.
+ * The members of the {@link ActionCache} service: `save` a set of paths under a
+ * key and `restore` them in a later job.
  *
  * @public
  */
@@ -1566,19 +1571,12 @@ interface PairsOptions {
  * @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.
+ * the runner's variable name — see `ActionInput.variable` for why that
+ * matters.
  *
- * These are grouped statics over one concept reaching nothing but `Config` —
- * not a namespace object over engines.
+ * `lines` is the `@actions/core`-faithful newline split; `list` and `pairs`
+ * read the richer shapes workflow authors write — JSON arrays, bullet lists,
+ * comments and `key=value` pairs.
  *
  * **The absence contract, shared by every accessor:** the runner writes `""`
  * for an input the workflow left out, and the provider reads an empty string
@@ -1633,10 +1631,9 @@ export declare class ActionInput {
    * **An input whose documented meaning is "set it empty to disable this"
    * cannot be read with `Config.withDefault`.** Empty is classified as missing
    * *before* the default is consulted, so the default substitutes and the
-   * documented behavior can never happen. A live action shipped exactly that
-   * for its whole lifetime: `action.yml` promised `release-prefix: ""` would
-   * disable retry, and it never could. `Config.option` is the shape that
-   * distinguishes the states:
+   * documented behavior can never happen: if `action.yml` promises
+   * `release-prefix: ""` disables retry, a `withDefault` read makes that
+   * impossible. `Config.option` is the shape that distinguishes the states:
    *
    * ```ts
    * Config.option(ActionInput.string("release-prefix"))
@@ -1652,8 +1649,7 @@ export declare class ActionInput {
    * no-default case, and it is the manifest default — when there is one — that
    * makes the unsupplied and explicitly-empty cases distinguishable at all.
    *
-   * Two consequences follow from how the runner actually behaves, both
-   * confirmed against `actions/runner` and on a live runner:
+   * Two consequences follow from how the runner actually behaves:
    *
    * - **The runner publishes a variable for every declared input**, so *absent*
    *   is a state a runner never produces. The `Some` branch above depends on
@@ -1675,8 +1671,8 @@ export declare class ActionInput {
    * 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`.
+   * default does NOT swallow it, so a malformed `dry-run` never quietly reads
+   * as `false`.
    */
   static boolean(name: string): Config.Config<boolean>;
   /**
@@ -1743,10 +1739,8 @@ export declare class ActionInput {
    * @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.
+   * combination of these in the same input — so a workflow author's first
+   * guess works.
    *
    * Parsing order, applied per newline/comma-separated item after trimming:
    *
@@ -1779,9 +1773,9 @@ export declare class ActionInput {
    * Only the **first** `=` splits, so a value may contain one.
    *
    * An **empty key** (`=value`, or a bare `=`) is always rejected: `{ "": v }`
-   * cannot be what a workflow meant, and the damage lands far from the typo —
-   * an empty key became a repository filter that matched nothing, and the run
-   * reported zero results with no indication why. An empty **value** (`key=`)
+   * cannot be what a workflow meant, and the damage would land far from the
+   * typo — an empty key becomes a filter that matches nothing, and the run
+   * reports zero results with no indication why. An empty **value** (`key=`)
    * is accepted by default, because setting a property to the empty string is
    * legitimate; pass `requireValue` to reject it. Every rejection names the
    * offending line.
@@ -1805,9 +1799,8 @@ export declare class ActionInput {
    *
    * There is no `schemaOption`: `ActionInput.schema(name, S).pipe(Config.option)`
    * yields `Config<Option<A>>` with missing → `None` and a malformed value
-   * still failing — core's documented `Config.option` behaviour ("validation
-   * errors ... still propagate", `Config.ts`), which is exactly the
-   * missing-versus-malformed split above.
+   * still failing — core's `Config.option` lets validation errors propagate,
+   * which is exactly the missing-versus-malformed split above.
    */
   static schema<A, I>(name: string, schema: Schema.Codec<A, I>): Config.Config<A>;
   /**
@@ -1817,7 +1810,7 @@ export declare class ActionInput {
    * The record dual-accepts, and the split is the `INPUT_` prefix:
    *
    * - A key already spelled as a runner variable (`INPUT_BIOME-VERSION`,
-   *   `PLAIN_VAR`) is read verbatim, exactly as before.
+   *   `PLAIN_VAR`) is read verbatim.
    * - Any other key is treated as an **input name**, `with:`-block style —
    *   `{ "biome-version": "2.3.14" }` — and serves the variable this module
    *   derives for it (`ActionInput.variable`). This is the spelling to
@@ -1834,11 +1827,10 @@ export declare class ActionInput {
    * installs ({@link ActionInput.providerOver} via `layerDefault`) — so a
    * bare `Config.String("biome-version")` resolves under this provider
    * exactly as it does inside `Action.run`. Nested and numeric paths pass
-   * through as the joined spelling only, as ever.
+   * through as the joined spelling only.
    *
-   * The source package's `ActionsConfigProvider` behaviors are otherwise
-   * preserved exactly: the path is joined with `_`, spaces become underscores
-   * and the whole is uppercased; and an **empty string reads as absent**,
+   * Otherwise the path is joined with `_`, spaces become underscores and the
+   * whole is uppercased; and an **empty string reads as absent**,
    * because the runner sets unsupplied inputs to `""` and treating that as
    * present would make every optional input look supplied. That rule applies
    * to input-name entries too: `{ "flag": "" }` is an unsupplied input.
@@ -1856,9 +1848,7 @@ export declare class ActionInput {
    * `TARGET-BRANCH`, never matches, and the read falls through to whatever
    * default the call site supplies. It **fails green**: nothing errors, the
    * suite passes against the default, and the test's name claims it proved the
-   * input was read. A consuming action's integration harness did exactly this
-   * and stayed green across several commits while a supplied `target-branch`
-   * silently did nothing.
+   * input was read.
    *
    * Runner-variable keys (`INPUT_TARGET-BRANCH`, `PLAIN_VAR`) are unaffected —
    * they are already in the spelling `fromEnv` produces, and they resolve. The
@@ -1871,9 +1861,8 @@ export declare class ActionInput {
    * 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`.
+   * `ConfigProvider.ConfigProvider` is a `Context.Reference`, so this is a
+   * reference override rather than a service.
    *
    * A parameterized layer factory mints a fresh reference per call; bind it to
    * a `const` rather than calling it at each composition site.
@@ -1891,10 +1880,9 @@ export declare class ActionInput {
    * 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
+   * This exists because the runner exposes inputs as `INPUT_<MANGLED>`
+   * variables, so a plain-named lookup finds nothing and a bare `Config` read
+   * would silently fall back to its `withDefault`. 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.
    *
@@ -1945,7 +1933,7 @@ export declare class ActionInput {
    * `ActionInput.provider` dual-accepts both spellings, so neither can miss.
    *
    * When none is installed, a **fresh** `ConfigProvider.fromEnv()`
-   * is built rather than reading the reference's default: v4 caches that
+   * is built rather than reading the reference's default: core 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
@@ -2024,7 +2012,8 @@ declare const OidcClaims_base: Schema.Class<OidcClaims, Schema.Struct<{
  */
 export declare class OidcClaims extends OidcClaims_base {}
 /**
- * The {@link OidcTokenIssuer} service shape.
+ * The members of the {@link OidcTokenIssuer} service: request an ID `token`
+ * and read its decoded `claims`, both failing with {@link OidcTokenError}.
  *
  * @public
  */
@@ -2060,9 +2049,9 @@ interface OidcTokenIssuerShape {
    *
    * 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.
+   * {@link OidcTokenIssuer.layerFor} answers with real, decodable claims, so
+   * a test cannot silently skip the path under test because the double
+   * returned a token that is not a JWT.
    */
   readonly claims: (audience?: string) => Effect.Effect<OidcClaims, OidcTokenError>;
 }
@@ -2091,16 +2080,22 @@ declare const OidcTokenIssuer_base: Context.ServiceClass<OidcTokenIssuer, "@effe
  * @public
  */
 export declare class OidcTokenIssuer extends OidcTokenIssuer_base {
+  /**
+   * The live issuer, requesting tokens from the runner's token service.
+   *
+   * @remarks
+   * Fails with {@link OidcTokenError} (`unavailable`) at use when the workflow
+   * lacks `permissions: id-token: write`.
+   */
   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.
+   * placeholder, so this token would fail any verifier. It exists because a
+   * double returning a synthetic non-JWT would make the provenance path
+   * structurally unreachable in a test.
    */
   static readonly unsignedTokenFor: (claims: OidcClaims) => Redacted.Redacted<string>;
   /** A test double. Unstubbed members die rather than answering with a non-token. */
@@ -2122,7 +2117,8 @@ export declare class OidcTokenIssuer extends OidcTokenIssuer_base {
 //#endregion
 //#region src/ActionsIdentityToken.d.ts
 /**
- * The Actions side of `@effected/sbom`'s inverted OIDC contract.
+ * Serves `@effected/sbom`'s `IdentityToken` contract from the runner's own OIDC
+ * token service, so signing an SBOM inside a workflow needs no further wiring.
  *
  * @remarks
  * `@effected/sbom` declares `IdentityToken` — one method, one audience,
@@ -2174,7 +2170,8 @@ export declare class ActionsIdentityToken {
 //#endregion
 //#region src/ActionsProvenance.d.ts
 /**
- * The Actions side of `@effected/sbom`'s SLSA provenance constructor.
+ * Builds the current run's SLSA provenance from the runner's OIDC claims: the
+ * Actions side of `@effected/sbom`'s `SlsaProvenance.forGitHubWorkflow`.
  *
  * @remarks
  * `SlsaProvenance.forGitHubWorkflow` is total and does the real work, but it
@@ -2279,6 +2276,7 @@ export declare class ArtifactError extends ArtifactError_base {
 interface ArtifactItem {
   /** The database id, which is what `download` takes. */
   readonly id: number;
+  /** The name the artifact was uploaded under. */
   readonly name: string;
   /** The size of the stored zip, in bytes. */
   readonly size: number;
@@ -2317,6 +2315,7 @@ interface UploadOptions {
  * @public
  */
 interface UploadResult {
+  /** The new artifact's database id, which `download` takes. */
   readonly id: number;
   /** The size of the uploaded zip, in bytes. */
   readonly size: number;
@@ -2340,15 +2339,17 @@ interface DownloadResult {
   readonly downloadPath: string;
 }
 /**
- * A reference to an artifact that is no longer there.
+ * The id of an artifact that `delete` removed.
  *
  * @public
  */
 interface ArtifactRef {
+  /** The deleted artifact's database id. */
   readonly id: number;
 }
 /**
- * The {@link Artifact} service shape.
+ * The members of the {@link Artifact} service: upload, list, get, download and
+ * delete, each failing with {@link ArtifactError}.
  *
  * @public
  */
@@ -2387,14 +2388,10 @@ declare const Artifact_base: Context.ServiceClass<Artifact, "@effected/github-ac
  * 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.
+ * **This surface is provisional.** It has not yet been shaped by a real call
+ * site, so it may be reworked once a consumer adopts it. It covers the current
+ * run only: there is no cross-run lookup, and adding one later would be
+ * additive.
  *
  * @example
  * ```ts
@@ -2516,33 +2513,59 @@ type BlobEnvelopeError = NotABlobEnvelopeError | TruncatedBlobEnvelopeError | Un
  * [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.
+ * Three properties earn the format:
+ *
+ * - **The magic prefix makes an unframed blob legible.** Raw, unframed bytes
+ *   decode as {@link NotABlobEnvelopeError} rather than as garbage metadata, so
+ *   a store holding entries written without an envelope produces a clean miss
+ *   instead of a corrupt read.
+ * - **The version lives in the blob, not in the key.** A format revision is
+ *   detected on read and reported typed
+ *   ({@link UnsupportedBlobEnvelopeVersionError}), so **keys stay stable** and
+ *   old entries age out naturally rather than needing a `v2/...` key prefix.
  * - **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.
+ *   the caller owns *meaning*. Fields like a cache tag or a duration are
+ *   schema fields, not bytes at fixed offsets in a private codec.
  *
  * **Pure**: `Result`-returning, no IO, no service — the framing is testable
  * from a byte array, which is the point.
  *
+ * @example
+ * ```ts
+ * import { BlobEnvelope } from "@effected/github-actions";
+ * import { Result, Schema } from "effect";
+ *
+ * const Meta = Schema.Struct({ tag: Schema.String });
+ *
+ * const framed = BlobEnvelope.encodeResult({ tag: "v1" }, new Uint8Array([1, 2, 3]), Meta);
+ * if (Result.isSuccess(framed)) {
+ *   const read = BlobEnvelope.decodeResult(framed.success, Meta);
+ *   // => Result.succeed({ metadata: { tag: "v1" }, body: Uint8Array [1, 2, 3] })
+ * }
+ * ```
+ *
  * @public
  */
 export declare class BlobEnvelope {
   private constructor();
-  /** The version this build writes. */
+  /** The envelope version this build writes and accepts. */
   static readonly version: number;
-  /** Frame metadata and a body into a single blob. */
+  /**
+   * Frame metadata and a body into a single blob.
+   *
+   * @returns a `Result` holding the framed bytes, or a
+   * {@link BlobMetadataEncodeError} when `metadata` does not satisfy `schema`
+   */
   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. */
+  /**
+   * Read a framed blob back into its metadata and body.
+   *
+   * @returns a `Result` holding the decoded metadata and a copy of the body, or
+   * a {@link BlobEnvelopeError}: {@link NotABlobEnvelopeError} for unframed
+   * bytes, {@link TruncatedBlobEnvelopeError},
+   * {@link UnsupportedBlobEnvelopeVersionError}, or
+   * {@link BlobMetadataDecodeError} when the metadata fails `schema`
+   */
   static decodeResult<A, I>(bytes: Uint8Array, schema: Schema.Codec<A, I>): Result.Result<{
     readonly metadata: A;
     readonly body: Uint8Array;
@@ -2586,12 +2609,19 @@ interface StoredBlob<A> {
   readonly body: Uint8Array;
 }
 /**
- * The {@link BlobStore} service shape.
+ * The members of the {@link BlobStore} service: `get`, `put` and `has` over
+ * blobs that carry the caller's own metadata.
  *
  * @public
  */
 interface BlobStoreShape {
-  /** Read a blob, or nothing if the key is absent. */
+  /**
+   * Read a blob, or nothing if the key is absent.
+   *
+   * @remarks
+   * Fails with {@link BlobStoreError}, or a {@link BlobEnvelopeError} when the
+   * stored bytes are not a valid envelope for `schema`.
+   */
   readonly get: <A, I>(key: string, schema: Schema.Codec<A, I>) => Effect.Effect<Option.Option<StoredBlob<A>>, BlobStoreError | BlobEnvelopeError>;
   /** Write a blob. */
   readonly put: <A, I>(key: string, blob: StoredBlob<A>, schema: Schema.Codec<A, I>) => Effect.Effect<void, BlobStoreError | BlobEnvelopeError>;
@@ -2604,7 +2634,9 @@ interface BlobStoreShape {
  * @public
  */
 interface S3Config {
+  /** The bucket name. */
   readonly bucket: string;
+  /** The bucket's region, used for SigV4 signing and the default AWS endpoint. */
   readonly region: string;
   /**
    * A custom endpoint, e.g. `https://<account>.r2.cloudflarestorage.com`.
@@ -2616,7 +2648,9 @@ interface S3Config {
    * DNS that none of them provide the same way.
    */
   readonly endpoint?: string | undefined;
+  /** The access key id. */
   readonly accessKeyId: string;
+  /** The secret access key, declassified once and masked in the runner log. */
   readonly secretAccessKey: Redacted.Redacted<string>;
   /** For temporary credentials. */
   readonly sessionToken?: Redacted.Redacted<string> | undefined;
@@ -2629,14 +2663,15 @@ declare const BlobStore_base: Context.ServiceClass<BlobStore, "@effected/github-
  *
  * @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.
+ * by {@link BlobEnvelope}. The metadata channel is the reason this exists:
+ * fields like a cache tag or a duration travel as schema-typed metadata, and a
+ * format revision is detected in the blob rather than by prefixing keys.
+ *
+ * Deliberately no `list` and no `delete`: eviction belongs to the backend, and
+ * both backends already have one.
  *
- * Deliberately no `list` and no `delete`: eviction belongs to the backend, both
- * backends already have one, and no consumer asked for either.
+ * Backends: {@link BlobStore.layerS3}, `GitHubCacheBlobStore.layer` and the
+ * in-memory {@link BlobStore.layerMemory}.
  *
  * @example
  * ```ts
@@ -2694,9 +2729,9 @@ export declare class BlobStore extends BlobStore_base {
  * 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.
+ * why this backend lives in its own module rather than beside the S3 one: it,
+ * `ActionCache` and `Artifact` are the only three modules that import the
+ * Azure client.
  *
  * **Only reachable from a `uses:` step.** The runner injects
  * `ACTIONS_RESULTS_URL` and `ACTIONS_RUNTIME_TOKEN` into action execution
@@ -2721,7 +2756,14 @@ export declare class BlobStore extends BlobStore_base {
  */
 export declare class GitHubCacheBlobStore {
   private constructor();
-  /** The backend, over the real Azure client. */
+  /**
+   * The backend, over the real Azure client.
+   *
+   * @remarks
+   * Requires `ActionEnvironment` for `ACTIONS_RESULTS_URL` and
+   * `ACTIONS_RUNTIME_TOKEN`; fails with `BlobStoreError` (`misconfigured`) when
+   * either is absent.
+   */
   static readonly layer: Layer.Layer<BlobStore, never, HttpClient.HttpClient | ActionEnvironment>;
   /**
    * The backend, over a supplied transport.
@@ -2835,8 +2877,7 @@ export declare class CheckDocumentStamp extends CheckDocumentStamp_base {
  * render was byte-identical, so no write was issued. `stale` — the document
  * already carries regions from a more recent run, so the pass was dropped
  * without writing (only possible when {@link CheckDocumentOptions.stamp} is
- * set). A plain literal union: callers that ignored `flush`'s old `void`
- * success stay compile-compatible.
+ * set).
  *
  * @public
  */
@@ -2946,7 +2987,8 @@ interface CheckDocumentOptions {
   readonly sinkTimeout?: Duration.Input | undefined;
 }
 /**
- * The check-run → document reconciler's surface.
+ * The members of the {@link CheckDocument} service: `report` a check's state,
+ * read the `checks` registry and `flush` the document.
  *
  * @public
  */
@@ -2970,8 +3012,7 @@ interface CheckDocumentShape {
    * Rendering unchanged state issues no write. Call it at the end of a run;
    * the layer's finalizer also runs it, so the last burst of reports lands
    * even when the scope closes inside the quiet window. The outcome says
-   * what the pass did — `written`, `unchanged` or `stale` — and callers
-   * that ignore it stay exactly as they were.
+   * what the pass did — `written`, `unchanged` or `stale`.
    */
   readonly flush: Effect.Effect<CheckFlushOutcome, CheckDocumentError>;
 }
@@ -3154,8 +3195,7 @@ interface PathPrependOptions {
 }
 /**
  * Child-process environment construction: prepending directories to `PATH`
- * without falling into the three traps that each cost a real consumer a
- * cross-OS matrix round.
+ * without falling into three cross-platform traps.
  *
  * @remarks
  * Spawning a child with directories prepended to `PATH` is one tiny concern
@@ -3188,9 +3228,7 @@ interface PathPrependOptions {
  * taken as an argument — which is what makes every platform branch
  * exercisable from a test on any host. The sanctioned exceptions are
  * *defaults a caller can override by passing the value*: `ActionInput.provider`'s
- * `env = process.env` and `DetachedProcess.spawn`'s `base`. A structural test
- * (`__test__/ambientReads.test.ts`) holds the list closed; a new default is
- * added there with its reason, never silently.
+ * `env = process.env` and `DetachedProcess.spawn`'s `base`.
  *
  * @public
  */
@@ -3278,7 +3316,7 @@ declare const DetachedLogUnavailableError_base: Schema.Class<DetachedLogUnavaila
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Raised when a detached child cannot be started, waited for, or reaped.
+ * Raised when the log file for a detached child's output cannot be opened.
  *
  * @public
  */
@@ -3530,8 +3568,7 @@ export declare class DetachedProcess {
    * @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.
+   * runner and too short on a slow one.
    *
    * 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
@@ -3545,11 +3582,9 @@ export declare class DetachedProcess {
    * @remarks
    * The probe {@link DetachedProcess.awaitReady} almost always wants: an HTTP
    * `GET` at a port the child is still binding, where connection-refused *is*
-   * "not up yet". The consumers that hand-rolled the polling wrote exactly
-   * this probe around it, and each had to discover the same subtlety — the
-   * probe's error channel must stay empty, because `awaitReady` deliberately
-   * propagates probe failures, and a refused connection is not a failure of
-   * the probe.
+   * "not up yet". The probe's error channel must stay empty, because
+   * `awaitReady` deliberately propagates probe failures, and a refused
+   * connection is not a failure of the probe.
    *
    * So this probe never fails: a refused connection, any other transport
    * error and a non-2xx answer all collapse to `false`, leaving
@@ -3558,9 +3593,9 @@ export declare class DetachedProcess {
    * only sound because every failure an HTTP readiness check can see means
    * the same thing here. The cost is the documented one: a *misconfigured*
    * probe — a typo'd port, a wrong path — is indistinguishable from a child
-   * that never came up, and reports as `notReady` only after the full budget.
-   * A probe whose failures are meaningfully distinct should stay a
-   * hand-written effect with those failures in `E`.
+   * that never came up, and reports as {@link DetachedNotReadyError} only after
+   * the full budget. A probe whose failures are meaningfully distinct should
+   * stay a hand-written effect with those failures in `E`.
    *
    * The request goes through core's `HttpClient` — `Action.run` provides it
    * ambiently — rather than a bare `fetch`, per the package rule that
@@ -3807,8 +3842,7 @@ interface GitHubSchemaTable<Row> {
  * a backtick gets a wider delimiter; a URL containing spaces or parentheses
  * is angle-bracketed.
  *
- * This module is the package's **only** importer of `@effected/markdown` — a
- * structural test pins that, on the same terms as the Azure confinement — so
+ * This module is the package's **only** importer of `@effected/markdown`, so
  * an action that never renders markdown never links the engine.
  *
  * **Renders cannot fail, so do not `Effect.try`-wrap them.** The serializer's
@@ -3861,8 +3895,8 @@ export declare class GitHubMarkdown {
    * each cell is the field value's **encoded** string form — a branded or
    * typed field projects through its own codec, so the vocabulary lives
    * with the schema instead of being respelled at every call site, and a
-   * row can no longer transpose columns because it is a typed object, not
-   * a positional array.
+   * row cannot transpose columns because it is a typed object, not a
+   * positional array.
    *
    * A field whose encoded side is not a string has no string projection to
    * borrow; the type of `options` makes its column's `format` — and
@@ -3874,8 +3908,8 @@ export declare class GitHubMarkdown {
    * {@link GitHubMarkdown.table}, so escaping is inherited and identical
    * rows produce identical output. Rows are already-decoded values of the
    * schema's type, so encoding them is total in practice; a value smuggled
-   * past the types throws the codec's `SchemaError` as a defect — same
-   * posture as the serializer arm above, **not** a silent fallback.
+   * past the types throws the codec's `SchemaError` as a defect, **not** a
+   * silent fallback.
    *
    * This is the **only** member where a throw is reachable at runtime, and
    * neither route is the serializer — see the no-wrapping remark on
@@ -3941,8 +3975,8 @@ export declare class GitHubMarkdown {
    * its fragments as markdown, so `raw` adds no behavior — it adds the
    * *statement* that a value is already rendered. Use it where a fragment
    * from elsewhere enters a composition and a reader would otherwise wonder
-   * whether it still needs escaping. It replaces the `Html.make` idiom,
-   * which passes markdown through correctly but announces the wrong intent.
+   * whether it still needs escaping. Prefer it to `Html.make`, which passes
+   * markdown through correctly but announces the wrong intent.
    */
   static raw(markdown: string): string;
 }
@@ -4022,9 +4056,8 @@ interface ClientLayerOptions extends ReadOptions {
  * 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
+ * One of the two seams between this package and `@effected/github` — 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`.
  *
@@ -4036,16 +4069,14 @@ interface ClientLayerOptions extends ReadOptions {
  * **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
+ * a one-hour token for a permanent one. So the 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:
+ * Every member's `R` says exactly which services it needs, and this table says
+ * which parts of each it touches, so a partial double is built from the
+ * documentation rather than from a stack trace:
  *
  * | Member | `ActionState` | `ActionOutputs` | `GitHubApp` |
  * | --- | --- | --- | --- |
@@ -4094,10 +4125,11 @@ export declare class GitHubToken {
    * 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.
+   * Fails with {@link GitHubTokenError} when it is spent, and with
+   * {@link ActionStateError} when no token was persisted. Without that check a
+   * `main` phase that outlived the hour would simply start answering `401` with
+   * no explanation — the hardest failure in this lifecycle to diagnose from a
+   * workflow log.
    */
   static readonly read: (options?: ReadOptions | undefined) => Effect.Effect<InstallationToken, ActionStateError | GitHubTokenError, ActionState>;
   /**
@@ -4211,9 +4243,8 @@ declare const ManagedDocument_base: Schema.Class<ManagedDocument, Schema.Struct<
  * region carrying the latest content, which is what makes a check that
  * resolves many times safe to re-render.
  *
- * The region engine is `@effected/templates`' pure `SectionDocument` —
- * reused, not reinvented — fixed to the HTML comment style and a
- * region-specific phrase. Everything here is string → string; the GitHub
+ * The region engine is `@effected/templates`' pure `SectionDocument`, fixed to
+ * the HTML comment style and a region-specific phrase. Everything here is string → string; the GitHub
  * write path composes this with `PullRequestComment` (whose `CommentMarker`
  * renders the *same* sentinel for the same namespace and key) or a PR-body
  * update in `@effected/github`.
@@ -4310,7 +4341,7 @@ export declare class ManagedDocument extends ManagedDocument_base {
    * call keeps its content *and* its metadata untouched — and never
    * participates in region addressability: a region is found by key alone,
    * so changing metadata updates the region in place. A two-element entry
-   * behaves exactly as it always has. Names must match
+   * supplies no metadata. Names must match
    * `[A-Za-z][A-Za-z0-9_-]*` and values may not contain `"` or a line
    * break; violations fail typed as `invalidAttribute`.
    *
@@ -4470,7 +4501,9 @@ interface ProvisionedFile {
   readonly binDir: string;
 }
 /**
- * The {@link ToolInstaller} service shape.
+ * The members of the {@link ToolInstaller} service: find, download, extract and
+ * cache tools in the runner's tool cache, each failing with
+ * {@link ToolInstallerError}.
  *
  * @public
  */
@@ -4488,9 +4521,9 @@ interface ToolInstallerShape {
    * location contract ({@link ToolInstaller.cachePath}); the directory's
    * *interior* layout is whatever its writer produced, which is not
    * necessarily what this consumer's own `cacheDir` would have written.
-   * Validate the layout of a foreign hit before relying on it — applying an
+   * Validate the layout of a foreign hit before relying on it — an
    * assumption from your own install path (an archive-wrapper subdirectory,
-   * say) to a foreign entry is a real shipped bug.
+   * say) may not hold for a foreign entry.
    */
   readonly find: (tool: string, version: string) => Effect.Effect<Option.Option<string>>;
   /**
@@ -4582,6 +4615,13 @@ declare const ToolInstaller_base: Context.ServiceClass<ToolInstaller, "@effected
  * @public
  */
 export declare class ToolInstaller extends ToolInstaller_base {
+  /**
+   * The live installer, over the runner's tool cache, `HttpClient` and `tar`.
+   *
+   * @remarks
+   * The cache root comes from `RUNNER_TOOL_CACHE`, resolved once at layer
+   * construction.
+   */
   static readonly layer: Layer.Layer<ToolInstaller, never, ActionEnvironment | FileSystem.FileSystem | Path.Path | HttpClient.HttpClient | ChildProcessSpawner.ChildProcessSpawner>;
   /**
    * Where a tool lives in the cache.
@@ -4610,9 +4650,8 @@ export declare class ToolInstaller extends ToolInstaller_base {
    * otherwise have to stub it in every test. The default is the static layout
    * over `RUNNER_TOOL_CACHE`, or the same off-runner root `make` resolves
    * (`internal/runner.ts`). **That is a read of the ambient environment**,
-   * sanctioned here only because a double has no `ActionEnvironment` to ask —
-   * test-double-only, and listed as such in the package's ambient-read
-   * allowlist (`__test__/ambientReads.test.ts`).
+   * sanctioned here only because a double has no `ActionEnvironment` to ask,
+   * and limited to the test double.
    */
   static readonly makeTest: (overrides?: Partial<ToolInstallerShape>) => ToolInstallerShape;
   /** {@link ToolInstaller.makeTest} behind `Layer.succeed`. */
@@ -4735,7 +4774,7 @@ interface PackageManagerInstallOptions {
    * carrying no parseable SRI fails with `integrityMismatch` (the
    * could-not-verify arm), and a tarball that hashes to anything else fails
    * with `integrityMismatch` naming the tarball url. Absent, the registry's
-   * own `dist.integrity` is the authority, as before. A tool-cache hit is
+   * own `dist.integrity` is the authority. A tool-cache hit is
    * answered without re-verifying, exactly as the pin's own integrity is.
    */
   readonly nativeIntegrity?: Readonly<Record<string, string>> | undefined;
@@ -4842,7 +4881,8 @@ export declare const InstalledPackageManager: Schema.Union<readonly [typeof Ambi
  */
 export type InstalledPackageManager = typeof InstalledPackageManager.Type;
 /**
- * The {@link PackageManagerInstaller} service shape.
+ * The members of the {@link PackageManagerInstaller} service: `install` the
+ * exact package-manager version a pin names.
  *
  * @public
  */
@@ -4905,6 +4945,14 @@ declare const PackageManagerInstaller_base: Context.ServiceClass<PackageManagerI
  * @public
  */
 export declare class PackageManagerInstaller extends PackageManagerInstaller_base {
+  /**
+   * The live installer, caching through {@link ToolInstaller}.
+   *
+   * @remarks
+   * Fails with {@link PackageManagerInstallerError}; requires the runner's
+   * environment, a filesystem, `Path`, a child-process spawner and a
+   * `ToolInstaller`.
+   */
   static readonly layer: Layer.Layer<PackageManagerInstaller, never, ActionEnvironment | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner | ToolInstaller>;
   /** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
   static readonly makeTest: (overrides?: Partial<PackageManagerInstallerShape>) => PackageManagerInstallerShape;
@@ -4972,8 +5020,7 @@ export declare class Secret {
    * **Detached workers invert the masking model.** Masking works because the
    * runner parses this process's stdout; a *detached* child's stdout is a log
    * file no runner parses, so a mask emitted **inside** the worker is inert
-   * and writes the plaintext verbatim into that log — a shipped incident, not
-   * a hypothetical. The rule: **the parent masks, before the spawn** — call
+   * and writes the plaintext verbatim into that log. The rule: **the parent masks, before the spawn** — call
    * this member in the parent, where the runner is listening, and hand the
    * already-masked plaintext to the worker's environment. Inside the worker,
    * compose `ActionOutputs.layerDetached`, whose `setSecret` is a documented
@@ -5018,9 +5065,8 @@ export declare class Secret {
    * **In a detached worker, the mask this member emits is a leak.** The
    * `::add-mask::` command only masks when the runner parses this process's
    * stdout; a detached worker's stdout is a log file no runner parses, so
-   * there the command masks nothing *and* spells the plaintext into the log
-   * — a signing key shipped exactly that way for one round. A worker that
-   * signs (an S3-style `BlobStore` is the canonical case) must compose
+   * there the command masks nothing *and* spells the plaintext into the log.
+   * A worker that signs (an S3-style `BlobStore` is the canonical case) must compose
    * `ActionOutputs.layerDetached`, under which this member still returns the
    * raw key for the HMAC but the mask is a documented no-op; the masking
    * itself is the **parent's** job, done before the spawn via
@@ -5040,8 +5086,7 @@ export declare class Secret {
    * secret enters the ambient environment without wading through signing
    * keys and runner files.
    *
-   * The ruling on who mutates is unchanged by the name existing: **this
-   * package never mutates `process.env`.** Reads are seeded once, at layer
+   * **This package never mutates `process.env`.** Reads are seeded once, at layer
    * construction, through `ActionEnvironment`, and nothing here writes back
    * — a write from inside the kit would be invisible to that seeding and to
    * every consumer's assumptions about when the environment is stable. This
@@ -5063,13 +5108,10 @@ export declare class Secret {
    * Masking without declassification: the value is registered with
    * `::add-mask::` through the same route as every other member, and the
    * success channel is `void`, so a caller cannot come away holding the raw
-   * value at all. This is the register-only shape consumers previously spelled
-   * as a {@link Secret.forSigning} whose result was discarded — a spelling
-   * that lied to the audit vocabulary (a grep for signing found masking),
-   * contradicted forSigning's own once-at-construction guidance, and needed a
-   * comment to apologize for itself. The names are the vocabulary: a grep for
-   * this member finds every register-only site, and a grep for `forSigning`
-   * again finds only signing.
+   * value at all. Prefer it to calling {@link Secret.forSigning} and discarding
+   * the result, which would mislabel a masking site as a signing one. The names
+   * are the audit vocabulary: a grep for this member finds every register-only
+   * site, and a grep for `forSigning` finds only signing.
    *
    * The canonical caller masks every supplied credential input
    * unconditionally, before the logic that decides which of them will
@@ -5084,9 +5126,8 @@ export declare class Secret {
    * **In a detached worker, the mask this member emits is a leak.** The
    * `::add-mask::` command only masks when the runner parses this process's
    * stdout; a detached worker's stdout is a log file no runner parses, so
-   * there the command masks nothing *and* spells the plaintext into the log
-   * — a signing key shipped exactly that way for one round. A worker must
-   * compose `ActionOutputs.layerDetached`, under which the mask is a
+   * there the command masks nothing *and* spells the plaintext into the log.
+   * A worker must compose `ActionOutputs.layerDetached`, under which the mask is a
    * documented no-op; the masking itself is the **parent's** job, done
    * before the spawn via {@link Secret.forChildEnv} under the real layer.
    */
@@ -5102,5 +5143,5 @@ export declare class Secret {
   static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
 }
 //#endregion
-export type { ActionCacheShape, ActionEnvironmentShape, ActionLoggerShape, ActionOutputError, ActionOutputsShape, ActionRunOptions, ActionServices, ActionStateShape, AnnotationProperties, ArtifactItem, ArtifactRef, ArtifactShape, BlobEnvelopeError, BlobStoreShape, CacheKeyError, CheckDocumentOptions, CheckDocumentShape, CheckDocumentSink, CheckFlushOutcome, CheckRunConclusion, CheckRunProjection, ClientLayerOptions, DataBlobTransfer, DetachedProcessError, DetachedProcessOps, DetachedSpawnOptions, DownloadOptions, DownloadResult, DryRunShape, ExtractOptions, FileBlobTransfer, GitHubHeadingDepth, GitHubListOptions, GitHubRowSchema, GitHubSchemaTable, GitHubSchemaTableColumn, GitHubSchemaTableColumns, GitHubSchemaTableFormatRequiredKeys, GitHubSchemaTableFormattedColumn, GitHubSchemaTableOptions, ManagedDocumentSource, OidcTokenIssuerShape, PackageManagerInstallOptions, PackageManagerInstallerShape, PairsOptions, PathPrependEnv, PathPrependOptions, ProvisionFileOptions, ProvisionOptions, ProvisionedFile, ReadOptions, ReadinessOptions, RecordedOutputMember, RecordingOutputs, S3Config, StoredBlob, ToolDownloadOptions, ToolInstallerShape, UploadOptions, UploadResult, WithBufferOptions, WithStepOptions };
+export { type ActionCacheShape, type ActionEnvironmentShape, type ActionLoggerShape, type ActionOutputError, type ActionOutputsShape, type ActionRunOptions, type ActionServices, type ActionStateShape, type AnnotationProperties, type ArtifactItem, type ArtifactRef, type ArtifactShape, type BlobEnvelopeError, type BlobStoreShape, type CacheKeyError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, type CheckFlushOutcome, type CheckRunConclusion, type CheckRunProjection, type ClientLayerOptions, type DataBlobTransfer, type DetachedProcessError, type DetachedProcessOps, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, type DryRunShape, type ExtractOptions, type FileBlobTransfer, type GitHubHeadingDepth, type GitHubListOptions, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, type ManagedDocumentSource, type OidcTokenIssuerShape, type PackageManagerInstallOptions, type PackageManagerInstallerShape, type PairsOptions, type PathPrependEnv, type PathPrependOptions, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, type RecordedOutputMember, type RecordingOutputs, type S3Config, type StoredBlob, type ToolDownloadOptions, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand };
 //# sourceMappingURL=index.d.ts.map