@effected/github-actions 0.9.1 → 0.10.0

package/PackageManagerInstaller.js

@@ -50,7 +50,7 @@ var PackageManagerInstallerError = class extends Schema.TaggedError()("PackageMa
 		switch (this.reason) {
 			case "downloadFailed": return `Could not download ${pin}${this.subject === void 0 ? "" : ` from ${this.subject}`}`;
 			case "extractFailed": return `Could not extract ${pin}${this.subject === void 0 ? "" : ` (${this.subject})`}`;
-			case "integrityMismatch": return `Integrity mismatch for ${pin}: expected ${this.expected}, got ${this.actual}`;
+			case "integrityMismatch": return this.expected === void 0 || this.actual === void 0 ? `Could not verify the integrity of ${pin}${this.subject === void 0 ? "" : ` (${this.subject})`}` : `Integrity mismatch for ${pin}: expected ${this.expected}, got ${this.actual}`;
 			case "integrityMissing": return `The pin for ${pin} carries no integrity hash and requireIntegrity is set`;
 			case "unsupportedPlatform": return `No ${pin} build is published for ${this.subject}`;
 			case "layoutUnexpected": return `The ${pin} artifact does not have the expected layout${this.subject === void 0 ? "" : `: ${this.subject}`}`;

package/README.md

@@ -139,6 +139,18 @@ const program = Effect.gen(function* () {
 await Action.run(program, { layer: ActionCache.layer });
 ```
 
+`CacheKey.withNamespace(segment)` is the cache-bust case — a run that must match nothing an unbusted run wrote, and whose own entries must be invisible to unbusted runs:
+
+```ts
+import { CacheKey } from "@effected/github-actions";
+
+const key = CacheKey.of("Linux", "pnpm-store", "abc123").withNamespace("bust7");
+console.log(key.key, key.restoreKeys);
+// bust7-Linux-pnpm-store-abc123 []
+```
+
+Two decisions make that safe for any segment value, with no prefix reasoning at the call site. The segment goes **first**, so the namespaced key shares no prefix with an unnamespaced one — a restore key is a prefix match, and folding a bust token in later leaves an ordinary run's rung prefix-matching busted entries. And the ladder is **dropped**, so no rung reaches outside the namespace even when the segment happens to equal an ordinary leading segment. It is a safe default rather than a prohibition: follow with `withRestoreDepths` for a deliberate in-namespace ladder.
+
 `CacheKey.hashFiles` is byte-compatible with `@actions/glob`'s `hashFiles`, and `OidcTokenIssuer.claims` decodes the runner's OIDC token for a SLSA provenance predicate without verifying its signature — the token arrived over TLS from the runner's own token service, so the transport is the trust boundary and nothing here branches on the claims for authorization.
 
 `ActionsProvenance.capture` turns those claims into an `@effected/sbom` `SlsaProvenance` predicate, and `ActionsIdentityToken.layer` serves that package's narrow `IdentityToken` contract from the same issuer — the inversion that keeps the Actions runtime out of every consumer that only wants to emit an SBOM:
@@ -228,6 +240,30 @@ Every region the run writes then carries its `at` and `runId`, and a pass whose
 
 `CheckState` is the vocabulary both of them speak, and it is deliberately wider than GitHub's conclusion set — `running` is a state rather than the absence of one, and `user_interaction_required` names a pipeline waiting on a human. `projectCheckState` maps each onto the wire form GitHub wants, as a status plus a conclusion exactly when the status is `completed`.
 
+## Typed failures
+
+Four failure types in this package are **tagged unions of one error class per reason** rather than a single class carrying a `reason` field: `ActionOutputError`, `BlobEnvelopeError`, `CacheKeyError` and `DetachedProcessError`. Every one of those names still exists and still means the same set of outcomes, so no signature changed — each is now a type alias over its members:
+
+| Union | Members |
+| ----- | ------- |
+| `ActionOutputError` | `RunnerFileUnavailableError`, `RunnerFileWriteError`, `InvalidOutputNameError`, `OutputEncodeError`, `DetachedOutputError` |
+| `BlobEnvelopeError` | `NotABlobEnvelopeError`, `TruncatedBlobEnvelopeError`, `UnsupportedBlobEnvelopeVersionError`, `BlobMetadataDecodeError`, `BlobMetadataEncodeError` |
+| `CacheKeyError` | `CacheKeyReadError`, `CacheKeyBadPatternError` |
+| `DetachedProcessError` | `DetachedLogUnavailableError`, `DetachedSpawnFailedError`, `InvalidPidError`, `DetachedSignalFailedError`, `DetachedNotReadyError` |
+
+**Breaking, and how to migrate.** Code that branched on `error.reason` matches on `_tag` instead, which is what buys the split: one failure can be handled on its own with `Effect.catchTag`, and the rest stay in the error channel rather than being caught by a handler that only meant to answer one of them.
+
+```ts
+import { CacheKey } from "@effected/github-actions";
+import { Effect, Option } from "effect";
+
+const digest = CacheKey.hashMatching({ workspace: ".", patterns: ["**/pnpm-lock.yaml"] }).pipe(
+  Effect.catchTag("CacheKeyBadPatternError", () => Effect.succeed(Option.none<string>())),
+);
+// Effect<Option<string>, CacheKeyReadError, FileSystem | Path>
+// a bad pattern becomes "no digest"; a read failure stays in the error channel
+```
+
 ## Testing
 
 Every service ships `makeTest(overrides?)` and `layerTest(overrides?)`, with unstubbed members dying loudly and naming themselves — three recorded exceptions state why they default instead: `ActionEnvironment.makeTest` seeds the twelve `GITHUB_*`/`RUNNER_*` variables, `ActionLogger.makeTest` defaults to silent, and `DryRun.makeTest` defaults to rehearsing, the safe direction. `ActionEnvironment.makeTest`/`layerTest` also take the webhook event payload as an optional second argument, serving it directly instead of routing it through a `GITHUB_EVENT_PATH` filesystem read the stubbed filesystem could never satisfy:
@@ -255,7 +291,7 @@ const TestOutputs = ActionOutputs.layerTest({
 ## Features
 
 - `Action.run` / `ActionRuntime.layer` — the entry point and default runtime: environment, logger, outputs, state, the Node platform and an `HttpClient`.
-- `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default.
+- `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default. `pairs` always rejects an empty key (`=value`, whose damage lands far from the typo) and takes `requireValue` to reject an empty value too.
 - `ActionOutputs` — step outputs, JSON outputs, the job summary, exported variables, `PATH` additions, failure annotations and log masking.
 - `ActionState` / `ActionEnvironment` — persisted `pre`/`main`/`post` state, and the fiber-local `GITHUB_*`/`RUNNER_*` context read once from `process.env`.
 - `ActionLogger` — collapsible groups, buffered step transcripts (`withBuffer({ onSuccess: "discard" })` drops a green step's transcript entirely, while a failure, defect or interruption still flushes it), `withStep(name, effect, options?)` for the same buffering plus one summary line on success and a `❌ <name>` header above the transcript on failure, `::notice::` annotations, and the `Logger` that renders every `Effect.log*` as a workflow command.
@@ -263,15 +299,15 @@ const TestOutputs = ActionOutputs.layerTest({
 - `Secret` — the one declassification seam between a `Redacted` value and a plain string, masking before it returns plaintext.
 - `GitHubToken` — the App-token lifecycle shaped like the `pre`/`main`/`post` workflow: mint, verify scopes, persist, read, revoke.
 - `ActionCache` / `Artifact` — the runner's cache and artifact protocols over Twirp v2, excluded from the default runtime so a consumer that skips them never links Azure.
-- `CacheKey` — cache keys and their restore-key ladder, plus `hashFiles`/`matchingFiles`/`hashMatching` byte-compatible with `@actions/glob`.
+- `CacheKey` — cache keys and their restore-key ladder, `withNamespace(segment)` for a bust token or a shared-runner prefix, plus `hashFiles`/`matchingFiles`/`hashMatching` byte-compatible with `@actions/glob`.
 - `OidcTokenIssuer` — the runner's OIDC token service, with unverified claim decoding for provenance predicates.
 - `ActionsIdentityToken` / `ActionsProvenance` — the `@effected/sbom` seam: `layer` serves that package's `IdentityToken` contract from the runner's issuer, and `capture` builds a `SlsaProvenance` predicate out of the runner's OIDC claims.
 - `GitHubMarkdown` — the escaping-safe writer for GitHub surfaces: `table`, `tableFor(schema)`, `heading`, `link`, `code`, `codeBlock`, `list`, `details` and `raw`, and the package's only importer of `@effected/markdown`.
 - `ManagedDocument` — marker-delimited named regions in text a human also edits, for a sticky comment or a managed pull request description; content outside the regions survives byte-for-byte, and each region can carry marker metadata that round-trips through `entry(key)` without ever addressing the region.
 - `CheckState` / `projectCheckState` — the kit's check vocabulary, wider than GitHub's conclusions, and its projection onto the check-run wire form.
 - `CheckDocument` — the debounced check-to-document reconciler: report states as they change, and one write lands carrying the final one. `stamp` plus a readable sink lets two runs share one document, dropping a strictly older run's pass instead of clobbering the newer one; `flush` reports `written`, `unchanged` or `stale`.
-- `ToolInstaller` — download, extract and cache a toolchain in the runner's tool cache, with no `@actions/tool-cache` dependency.
-- `BlobStore` — durable `get`/`put`/`has` over bytes plus a metadata channel, backed by `layerS3` (SigV4-signed, no `@aws-sdk/*` dependency) or `GitHubCacheBlobStore.layer` (the runner's own cache); `layerMemory` runs the real envelope framing for tests.
+- `ToolInstaller` — download, extract and cache a toolchain in the runner's tool cache, with no `@actions/tool-cache` dependency; `ToolInstallerError` always names its `subject`.
+- `BlobStore` — durable `get`/`put`/`has` over `StoredBlob<A>` values (bytes plus caller-schema metadata; the type was named `Blob<A>` before, which collided with the global), backed by `layerS3` (SigV4-signed, no `@aws-sdk/*` dependency) or `GitHubCacheBlobStore.layer` (the runner's own cache); `layerMemory` runs the real envelope framing for tests.
 
 ## License
 

package/ToolInstaller.js

@@ -23,7 +23,7 @@ var ToolInstallerError = class extends Schema.TaggedError()("ToolInstallerError"
 	/** The HTTP status, when there was one. Drives the retry decision. */
 	status: Schema.optionalKey(Schema.Number),
 	/** What was being worked on — a url, an archive path, or a tool name. */
-	subject: Schema.optionalKey(Schema.String),
+	subject: Schema.String,
 	/** The extraction tool's own complaint, which is the only useful part of a tar failure. */
 	stderr: Schema.optionalKey(Schema.String),
 	/** The underlying failure, preserved structurally. */
@@ -76,6 +76,7 @@ const make = Effect.gen(function* () {
 		const requested = options?.destination;
 		if (requested === void 0) return fs.makeTempDirectory({ prefix: "effected-extract-" }).pipe(Effect.mapError((cause) => new ToolInstallerError({
 			reason: "extractFailed",
+			subject: "a temporary extraction directory",
 			cause
 		})));
 		return fs.makeDirectory(requested, { recursive: true }).pipe(Effect.as(requested), Effect.mapError((cause) => new ToolInstallerError({

package/index.d.ts

@@ -499,32 +499,93 @@ declare class ActionLogger extends ActionLogger_base {
 }
 //#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. `detached` — the member was called under
-   * {@link ActionOutputs.layerDetached}, where the channel it writes cannot
-   * reach the job that would read it.
-   */
-  readonly reason: Schema.Literals<readonly ["unavailable", "writeFailed", "invalidName", "encodeFailed", "detached"]>;
-  /** Which runner file was involved, by environment variable name. */
+declare const RunnerFileUnavailableError_base: Schema.Class<RunnerFileUnavailableError, Schema.TaggedStruct<"RunnerFileUnavailableError", {
+  /** The runner file involved, by environment variable name. */
+  readonly file: 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 RunnerFileUnavailableError extends RunnerFileUnavailableError_base {
+  get message(): string;
+}
+declare const RunnerFileWriteError_base: Schema.Class<RunnerFileWriteError, Schema.TaggedStruct<"RunnerFileWriteError", {
+  /** The runner file involved, by environment variable name. */
+  readonly file: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a runner file exists but could not be appended to.
+ *
+ * @public
+ */
+declare class RunnerFileWriteError extends RunnerFileWriteError_base {
+  get message(): string;
+}
+declare const InvalidOutputNameError_base: Schema.Class<InvalidOutputNameError, Schema.TaggedStruct<"InvalidOutputNameError", {
+  /** The offending name. */
+  readonly name: Schema.String;
+  /** The runner file involved, by environment variable name. */
   readonly file: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a name would corrupt the runner file's block structure.
+ *
+ * @public
+ */
+declare class InvalidOutputNameError extends InvalidOutputNameError_base {
+  get message(): string;
+}
+declare const OutputEncodeError_base: Schema.Class<OutputEncodeError, Schema.TaggedStruct<"OutputEncodeError", {
+  /** The output or variable name whose value would not encode. */
+  readonly name: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a value did not satisfy its schema.
+ *
+ * @public
+ */
+declare class OutputEncodeError extends OutputEncodeError_base {
+  get message(): string;
+}
+declare const DetachedOutputError_base: Schema.Class<DetachedOutputError, Schema.TaggedStruct<"DetachedOutputError", {
+  /** The runner file involved, by environment variable name. */
+  readonly file: 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.
+ * Raised when an output member was called under
+ * {@link ActionOutputs.layerDetached}.
  *
  * @public
  */
-declare class ActionOutputError extends ActionOutputError_base {
+declare class DetachedOutputError extends DetachedOutputError_base {
   get message(): string;
 }
+/**
+ * Anything that can go wrong publishing an output, variable or summary.
+ *
+ * @remarks
+ * **One class per failure, rather than one class with a `reason` field.** The
+ * runner file is required on the members that name one and the output name on
+ * the members that name one, so a value short a field is a compile error rather
+ * than a message reading `"undefined"`.
+ *
+ * @public
+ */
+type ActionOutputError = RunnerFileUnavailableError | RunnerFileWriteError | InvalidOutputNameError | OutputEncodeError | DetachedOutputError;
 /**
  * The {@link ActionOutputs} service shape.
  *
@@ -886,29 +947,50 @@ interface DataBlobTransfer {
 }
 //#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"]>;
+declare const CacheKeyReadError_base: Schema.Class<CacheKeyReadError, Schema.TaggedStruct<"CacheKeyReadError", {
   /** The path being read when it went wrong. */
-  readonly path: Schema.optionalKey<Schema.String>;
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a file or directory that was going to be hashed could not be
+ * read.
+ *
+ * @public
+ */
+declare class CacheKeyReadError extends CacheKeyReadError_base {
+  get message(): string;
+}
+declare const CacheKeyBadPatternError_base: Schema.Class<CacheKeyBadPatternError, Schema.TaggedStruct<"CacheKeyBadPatternError", {
   /** The pattern that would not compile. */
-  readonly pattern: Schema.optionalKey<Schema.String>;
+  readonly pattern: 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.
+ * Raised when a glob pattern would not compile.
  *
  * @public
  */
-declare class CacheKeyError extends CacheKeyError_base {
+declare class CacheKeyBadPatternError extends CacheKeyBadPatternError_base {
   get message(): string;
 }
+/**
+ * Anything that can go wrong deriving a cache key from the filesystem.
+ *
+ * @remarks
+ * Key *derivation* is pure and total once the bytes are in hand, so the two
+ * members here are the only things that can fail.
+ *
+ * **One class per failure, rather than one class with a `reason` field.** Each
+ * member carries exactly the fields its own message needs, so a value short a
+ * field is a compile error instead of a message reading `"undefined"` — and
+ * `Effect.catchTag` can recover from one of them without catching the other.
+ *
+ * @public
+ */
+type CacheKeyError = CacheKeyReadError | CacheKeyBadPatternError;
 declare const CacheKey_base: Schema.Class<CacheKey, Schema.Struct<{
   /** The components, most general first. */
   readonly segments: Schema.NonEmptyArray<Schema.String>;
@@ -1019,6 +1101,43 @@ declare class CacheKey extends CacheKey_base {
    * ```
    */
   withoutRestoreKeys(): CacheKey;
+  /**
+   * A copy of this key namespaced by `segment` — the whole key, ladder
+   * included.
+   *
+   * @remarks
+   * The cache-bust case: a run that must match nothing an unbusted run wrote,
+   * and whose own entries must be invisible to unbusted runs. Both halves of
+   * that are one intent, and spelling them separately is what makes the wrong
+   * version undetectable — a restore key is a **prefix match**, so folding the
+   * bust in *after* the retained prefix leaves an ordinary run's rung
+   * prefix-matching busted entries. The cache still appears to work, and
+   * quietly serves poisoned entries into unrelated runs.
+   *
+   * Two decisions make this safe for **any** segment value, with no prefix
+   * reasoning at the call site. The segment goes **first**, so the namespaced
+   * key shares no prefix with an unnamespaced one. And the ladder is
+   * **dropped**, so no rung of this key can reach outside the namespace even
+   * when the segment happens to equal an ordinary leading segment — which a
+   * prepend alone would not survive.
+   *
+   * Dropping the ladder is the safe default, not a prohibition: the segments
+   * are all still there, so a caller who wants one busted run to warm from
+   * another can follow with {@link CacheKey.withRestoreDepths} and get an
+   * in-namespace ladder deliberately.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   *
+   * const key = CacheKey.of("Linux", "pnpm-store", "abc123").withNamespace("bust7");
+   * key.key;          // "bust7-Linux-pnpm-store-abc123"
+   * key.restoreKeys;  // []
+   * ```
+   *
+   * @param segment - The namespace, e.g. a cache-bust token.
+   */
+  withNamespace(segment: string): CacheKey;
   /** Build a key from its segments. */
   static of(...segments: readonly [string, ...ReadonlyArray<string>]): CacheKey;
   /**
@@ -1103,7 +1222,7 @@ declare class CacheKey extends CacheKey_base {
    * 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>;
+  static readonly hashFiles: (files: readonly string[]) => Effect.Effect<Option.Option<string>, CacheKeyReadError, FileSystem.FileSystem>;
   /**
    * Every file under `workspace` that the pattern set matches.
    *
@@ -1132,7 +1251,7 @@ declare class CacheKey extends CacheKey_base {
     readonly workspace: string;
     /** Include patterns, with a leading `!` marking an exclusion. */
     readonly patterns: ReadonlyArray<string>;
-  }) => Effect.Effect<readonly string[], CacheKeyError, FileSystem.FileSystem | Path.Path>;
+  }) => Effect.Effect<readonly string[], CacheKeyBadPatternError | CacheKeyReadError, FileSystem.FileSystem | Path.Path>;
   /**
    * Hash every file under `workspace` that the pattern set matches.
    *
@@ -1163,7 +1282,7 @@ declare class CacheKey extends CacheKey_base {
   static readonly hashMatching: (options: {
     readonly workspace: string;
     readonly patterns: ReadonlyArray<string>;
-  }) => Effect.Effect<Option.Option<string>, CacheKeyError, FileSystem.FileSystem | Path.Path>;
+  }) => Effect.Effect<Option.Option<string>, CacheKeyBadPatternError | CacheKeyReadError, FileSystem.FileSystem | Path.Path>;
 }
 //#endregion
 //#region src/ActionCache.d.ts
@@ -1306,6 +1425,19 @@ declare class ActionCache extends ActionCache_base {
 }
 //#endregion
 //#region src/ActionInput.d.ts
+/**
+ * Options for {@link ActionInput.pairs}.
+ *
+ * @public
+ */
+interface PairsOptions {
+  /**
+   * Reject a pair whose value is empty (`key=`).
+   *
+   * @defaultValue `false` — an empty value is a legitimate empty string.
+   */
+  readonly requireValue?: boolean;
+}
 /**
  * Action inputs, read as `Config` values.
  *
@@ -1495,10 +1627,21 @@ declare class ActionInput {
    * @remarks
    * 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=`)
+   * 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.
+   *
    * Absent or `""` fails as missing data (see {@link ActionInput.string}) —
    * `Config.withDefault({})` is the idiom for an optional pairs input.
+   *
+   * @param name - The input name, unmangled.
+   * @param options - `requireValue` rejects a pair whose value is empty.
    */
-  static pairs(name: string): Config.Config<Record<string, string>>;
+  static pairs(name: string, options?: PairsOptions): Config.Config<Record<string, string>>;
   /**
    * A JSON-valued input, decoded through a schema.
    *
@@ -2127,19 +2270,8 @@ declare class Artifact extends Artifact_base {
 }
 //#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>;
+declare const NotABlobEnvelopeError_base: Schema.Class<NotABlobEnvelopeError, Schema.TaggedStruct<"NotABlobEnvelopeError", {
+  /** The underlying failure, preserved structurally. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -2147,9 +2279,71 @@ declare const BlobEnvelopeError_base: Schema.Class<BlobEnvelopeError, Schema.Tag
  *
  * @public
  */
-declare class BlobEnvelopeError extends BlobEnvelopeError_base {
+declare class NotABlobEnvelopeError extends NotABlobEnvelopeError_base {
+  get message(): string;
+}
+declare const TruncatedBlobEnvelopeError_base: Schema.Class<TruncatedBlobEnvelopeError, Schema.TaggedStruct<"TruncatedBlobEnvelopeError", {
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the frame ends mid-header or mid-metadata.
+ *
+ * @public
+ */
+declare class TruncatedBlobEnvelopeError extends TruncatedBlobEnvelopeError_base {
+  get message(): string;
+}
+declare const UnsupportedBlobEnvelopeVersionError_base: Schema.Class<UnsupportedBlobEnvelopeVersionError, Schema.TaggedStruct<"UnsupportedBlobEnvelopeVersionError", {
+  /** The envelope version found. */
+  readonly version: Schema.Number;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the envelope came from a newer revision of the format.
+ *
+ * @public
+ */
+declare class UnsupportedBlobEnvelopeVersionError extends UnsupportedBlobEnvelopeVersionError_base {
+  get message(): string;
+}
+declare const BlobMetadataDecodeError_base: Schema.Class<BlobMetadataDecodeError, Schema.TaggedStruct<"BlobMetadataDecodeError", {
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when well-framed metadata does not satisfy the caller's schema.
+ *
+ * @public
+ */
+declare class BlobMetadataDecodeError extends BlobMetadataDecodeError_base {
+  get message(): string;
+}
+declare const BlobMetadataEncodeError_base: Schema.Class<BlobMetadataEncodeError, Schema.TaggedStruct<"BlobMetadataEncodeError", {
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the value being stored does not satisfy its schema.
+ *
+ * @public
+ */
+declare class BlobMetadataEncodeError extends BlobMetadataEncodeError_base {
   get message(): string;
 }
+/**
+ * Anything that can go wrong reading or writing a blob envelope.
+ *
+ * @remarks
+ * **One class per failure, rather than one class with a `reason` field.** Each
+ * member carries exactly the fields its own message needs — the version is
+ * required on the one member that reports it — so a value short a field is a
+ * compile error rather than a message reading `"undefined"`.
+ *
+ * @public
+ */
+type BlobEnvelopeError = NotABlobEnvelopeError | TruncatedBlobEnvelopeError | UnsupportedBlobEnvelopeVersionError | BlobMetadataDecodeError | BlobMetadataEncodeError;
 /**
  * The schema-versioned frame that gives a stored blob a **metadata channel**.
  *
@@ -2223,7 +2417,7 @@ declare class BlobStoreError extends BlobStoreError_base {
  *
  * @public
  */
-interface Blob<A> {
+interface StoredBlob<A> {
   /** The caller's own metadata, decoded through the caller's own schema. */
   readonly metadata: A;
   /** The payload, verbatim. */
@@ -2236,9 +2430,9 @@ interface Blob<A> {
  */
 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>;
+  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: Blob<A>, schema: Schema.Codec<A, I>) => Effect.Effect<void, BlobStoreError | BlobEnvelopeError>;
+  readonly put: <A, I>(key: string, blob: StoredBlob<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>;
 }
@@ -2905,20 +3099,9 @@ declare class ChildEnv {
 }
 //#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>;
+declare const DetachedLogUnavailableError_base: Schema.Class<DetachedLogUnavailableError, Schema.TaggedStruct<"DetachedLogUnavailableError", {
+  /** The log file that could not be opened. */
+  readonly path: Schema.String;
   /** The underlying failure, preserved structurally. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
@@ -2927,9 +3110,77 @@ declare const DetachedProcessError_base: Schema.Class<DetachedProcessError, Sche
  *
  * @public
  */
-declare class DetachedProcessError extends DetachedProcessError_base {
+declare class DetachedLogUnavailableError extends DetachedLogUnavailableError_base {
   get message(): string;
 }
+declare const DetachedSpawnFailedError_base: Schema.Class<DetachedSpawnFailedError, Schema.TaggedStruct<"DetachedSpawnFailedError", {
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the detached child did not start.
+ *
+ * @public
+ */
+declare class DetachedSpawnFailedError extends DetachedSpawnFailedError_base {
+  get message(): string;
+}
+declare const InvalidPidError_base: Schema.Class<InvalidPidError, Schema.TaggedStruct<"InvalidPidError", {
+  /** The pid that was refused. */
+  readonly pid: Schema.Number;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a non-positive pid was handed to {@link DetachedProcess.reap}.
+ *
+ * @remarks
+ * See {@link DetachedProcess.reap} for why this is the most important value in
+ * the module: a non-positive pid targets a process *group*, not a process.
+ *
+ * @public
+ */
+declare class InvalidPidError extends InvalidPidError_base {
+  get message(): string;
+}
+declare const DetachedSignalFailedError_base: Schema.Class<DetachedSignalFailedError, Schema.TaggedStruct<"DetachedSignalFailedError", {
+  /** The pid that could not be signalled. */
+  readonly pid: Schema.Number;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a signal was refused, e.g. the process belongs to another user.
+ *
+ * @public
+ */
+declare class DetachedSignalFailedError extends DetachedSignalFailedError_base {
+  get message(): string;
+}
+declare const DetachedNotReadyError_base: Schema.Class<DetachedNotReadyError, Schema.TaggedStruct<"DetachedNotReadyError", {
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the readiness probe never held.
+ *
+ * @public
+ */
+declare class DetachedNotReadyError extends DetachedNotReadyError_base {
+  get message(): string;
+}
+/**
+ * Anything that can go wrong spawning, awaiting or reaping a detached child.
+ *
+ * @remarks
+ * **One class per failure, rather than one class with a `reason` field.** The
+ * pid is required on the two members that report one and the path on the one
+ * that does, so a value short a field is a compile error rather than a message
+ * reading `"undefined"`.
+ *
+ * @public
+ */
+type DetachedProcessError = DetachedLogUnavailableError | DetachedSpawnFailedError | InvalidPidError | DetachedSignalFailedError | DetachedNotReadyError;
 /**
  * The schema a pid crosses the phase boundary through.
  *
@@ -3083,7 +3334,7 @@ declare class DetachedProcess {
    * 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>;
+  static readonly spawn: (options: DetachedSpawnOptions) => Effect.Effect<ChildProcessSpawner.ProcessId, DetachedLogUnavailableError | DetachedSpawnFailedError, never>;
   /**
    * Poll a predicate until it holds.
    *
@@ -3147,7 +3398,7 @@ declare class DetachedProcess {
    * 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>;
+  static readonly reap: (pid: number, signal?: NodeJS.Signals | undefined) => Effect.Effect<boolean, DetachedSignalFailedError | InvalidPidError, never>;
   /**
    * The real operations: the production default for a
    * {@link DetachedProcessOps} parameter.
@@ -3924,7 +4175,7 @@ declare const ToolInstallerError_base: Schema.Class<ToolInstallerError, Schema.T
   /** 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>;
+  readonly subject: 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. */
@@ -4540,5 +4791,5 @@ declare class Secret {
   static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
 }
 //#endregion
-export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckDocumentStamp, type CheckFlushOutcome, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, ChildEnv, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedProcessOps, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, type PackageManagerInstallOptions, PackageManagerInstaller, PackageManagerInstallerError, type PackageManagerInstallerShape, type PathPrependEnv, type PathPrependOptions, ProcessId, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, type ToolDownloadOptions, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand, describeCause, projectCheckState };
+export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, type ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, BlobEnvelope, type BlobEnvelopeError, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyBadPatternError, type CacheKeyError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckDocumentStamp, type CheckFlushOutcome, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, ChildEnv, type ClientLayerOptions, type DataBlobTransfer, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, type DetachedProcessError, type DetachedProcessOps, DetachedSignalFailedError, DetachedSpawnFailedError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, NotABlobEnvelopeError, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, OutputEncodeError, type PackageManagerInstallOptions, PackageManagerInstaller, PackageManagerInstallerError, type PackageManagerInstallerShape, type PairsOptions, type PathPrependEnv, type PathPrependOptions, ProcessId, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, type S3Config, Secret, type StoredBlob, type ToolDownloadOptions, ToolInstaller, ToolInstallerError, type ToolInstallerShape, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand, describeCause, projectCheckState };
 //# sourceMappingURL=index.d.ts.map