@effected/github-actions 0.19.0 → 0.20.0

package/BlobEnvelope.js

@@ -85,31 +85,49 @@ const HEADER_BYTES = MAGIC.length + 1 + 4;
 * [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:
+* Three properties earn the format:
 *
-* - **The magic prefix makes a legacy blob legible.** Raw, unframed bytes
-*   decode as `notAnEnvelope` rather than as garbage metadata, so a store
-*   holding pre-envelope entries produces a clean miss instead of a corrupt
-*   read.
-* - **The version lives in the blob, not in the key.** A consumer previously
-*   namespaced keys (`v2/...`) to represent a format change, because there was
-*   no in-band version. Here a revision is detected on read and reported
-*   typed, so **keys stay stable** and old entries age out naturally.
+* - **The 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
 */
 var BlobEnvelope = class {
 	constructor() {}
-	/** The version this build writes. */
+	/** The envelope version this build writes and accepts. */
 	static version = VERSION;
-	/** 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(metadata, body, schema) {
 		const encoded = Schema.encodeUnknownResult(Schema.fromJsonString(schema))(metadata);
 		if (Result.isFailure(encoded)) return Result.fail(new BlobMetadataEncodeError({ cause: encoded.failure }));
@@ -122,7 +140,15 @@ var BlobEnvelope = class {
 		out.set(body, HEADER_BYTES + metaBytes.length);
 		return Result.succeed(out);
 	}
-	/** 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(bytes, schema) {
 		if (bytes.length < MAGIC.length || !MAGIC.every((byte, index) => bytes[index] === byte)) return Result.fail(new NotABlobEnvelopeError({}));
 		if (bytes.length < HEADER_BYTES) return Result.fail(new TruncatedBlobEnvelopeError({}));

package/BlobStore.githubCache.js

@@ -113,9 +113,9 @@ const make = (transfer) => Effect.gen(function* () {
 * 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
@@ -140,7 +140,14 @@ const make = (transfer) => Effect.gen(function* () {
 */
 var GitHubCacheBlobStore = class {
 	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 layer = Layer.effect(BlobStore, make(azure));
 	/**
 	* The backend, over a supplied transport.

package/BlobStore.js

@@ -44,14 +44,15 @@ var BlobStoreError = class extends Schema.TaggedError()("BlobStoreError", {
 *
 * @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, both
-* backends already have one, and no consumer asked for either.
+* Deliberately no `list` and no `delete`: eviction belongs to the backend, and
+* both backends already have one.
+*
+* Backends: {@link BlobStore.layerS3}, `GitHubCacheBlobStore.layer` and the
+* in-memory {@link BlobStore.layerMemory}.
 *
 * @example
 * ```ts

package/CacheKey.js

@@ -173,13 +173,12 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 	* 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

package/ChildEnv.js

@@ -1,8 +1,7 @@
 //#region src/ChildEnv.ts
 /**
 * 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
@@ -35,9 +34,7 @@
 * 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
 */

package/DetachedProcess.js

@@ -8,7 +8,7 @@ import { closeSync, openSync } from "node:fs";
 
 //#region src/DetachedProcess.ts
 /**
-* 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
 */
@@ -202,8 +202,7 @@ var DetachedProcess = 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
@@ -223,11 +222,9 @@ var DetachedProcess = 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
@@ -236,9 +233,9 @@ var DetachedProcess = 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

package/GitHubMarkdown.js

@@ -15,8 +15,7 @@ const passthrough = (value) => Html.make({ value });
 * `Markdown.stringifyResult` is total over every tree this module can
 * construct — its only failure is the hardening nesting-depth guard (cap
 * 256) — so the impossible arm is a defect, **not** a silent fallback to
-* unescaped string joining. The predecessor's fallback arm is the live
-* table-corruption defect this module exists to delete.
+* unescaped string joining.
 *
 * What makes the guard unreachable is not that these trees are small; it is
 * that **their depth does not depend on input**. A fragment handed to a
@@ -51,8 +50,7 @@ const block = (node) => render(Root.make({ children: [node] }));
 * 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
@@ -109,8 +107,8 @@ var GitHubMarkdown = 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
@@ -122,8 +120,8 @@ var GitHubMarkdown = 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
@@ -228,8 +226,8 @@ var GitHubMarkdown = 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) {
 		return markdown;

package/GitHubToken.js

@@ -64,9 +64,8 @@ const identified = (app, options, minted) => Effect.gen(function* () {
 * 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`.
 *
@@ -78,16 +77,14 @@ const identified = (app, options, minted) => Effect.gen(function* () {
 * **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` |
 * | --- | --- | --- | --- |
@@ -152,10 +149,11 @@ var GitHubToken = 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 read = Effect.fn("GitHubToken.read")(function* (options = {}) {
 		const token = yield* (yield* ActionState).get(options.stateKey ?? DEFAULT_KEY, InstallationToken);

package/ManagedDocument.js

@@ -103,9 +103,8 @@ const structural = (failure) => new ManagedDocumentError({
 * 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`.
@@ -222,7 +221,7 @@ var ManagedDocument = class ManagedDocument extends Schema.Class("ManagedDocumen
 	* 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`.
 	*

package/OidcTokenIssuer.js

@@ -126,9 +126,7 @@ const make = Effect.gen(function* () {
 	* `Redacted.value` does not appear in this module at all — the package's
 	* declassification invariant is that `Secret.ts` is the only place a secret
 	* becomes a string, and a wrap-then-immediately-unwrap here would be a
-	* genuine exception to it rather than a cosmetic one. A structural test over
-	* `src/` enforces this, and it caught exactly this call when the first draft
-	* did it the obvious way.
+	* genuine exception to it rather than a cosmetic one.
 	*/
 	const issue = Effect.fn("OidcTokenIssuer.token")(function* (audience) {
 		const bearer = yield* required(REQUEST_TOKEN);
@@ -179,16 +177,22 @@ const dies = unstubbed("OidcTokenIssuer.makeTest");
 * @public
 */
 var OidcTokenIssuer = class OidcTokenIssuer extends Context.Service()("@effected/github-actions/OidcTokenIssuer") {
+	/**
+	* 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 layer = Layer.effect(this, make);
 	/**
 	* 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 unsignedTokenFor = (claims) => Redacted.make(unsignedJwt({
 		alg: "RS256",

package/PackageManagerInstaller.js

@@ -353,9 +353,8 @@ const make = Effect.gen(function* () {
 	/**
 	* Whether a file is still pnpm's shebang-less placeholder (a `#`-led text
 	* file that is not a `#!` script) rather than the native binary meant to
-	* overlay it — the mark of an entry written by a version of this module
-	* that predates the overlay, or by a foreign writer that ran no lifecycle
-	* scripts. Anything else (a shebang, an executable's magic, an unreadable
+	* overlay it — the mark of an entry written without the overlay, by an
+	* older writer or a foreign one that ran no lifecycle scripts. Anything else (a shebang, an executable's magic, an unreadable
 	* or empty file) is left to the ordinary layout checks.
 	*/
 	const isPlaceholder = (file) => Effect.scoped(Effect.flatMap(fs.open(file), (handle) => handle.readAlloc(2))).pipe(Effect.map((head) => Option.match(head, {
@@ -715,6 +714,14 @@ const dies = unstubbed("PackageManagerInstaller.makeTest");
 * @public
 */
 var PackageManagerInstaller = class PackageManagerInstaller extends Context.Service()("@effected/github-actions/PackageManagerInstaller") {
+	/**
+	* 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 layer = Layer.effect(this, make);
 	/** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
 	static makeTest = (overrides = {}) => ({

package/README.md

@@ -7,10 +7,10 @@
 
 The GitHub Actions runtime for [Effect](https://effect.website) v4: the services an action needs to talk to the runner it is executing inside. `Action.run` composes the runtime, runs your program, renders a failure as an `::error::` annotation and sets the exit code. `ActionInput` reads workflow inputs as typed `Config` values — string, boolean, integer, redacted secret, multiline list, `key=value` pairs, or a schema-decoded JSON blob — with one absence rule shared by every accessor: unset and `""` are both missing data. `ActionOutputs`, `ActionState`, `ActionLogger` and a fiber-local `ActionEnvironment` round out the runner surface, alongside `ActionCache`, `Artifact`, a metadata-carrying `BlobStore` (S3-compatible or the runner's own cache), `OidcTokenIssuer` and `ToolInstaller` for the heavier protocols. A reporting suite — `GitHubMarkdown`, `ManagedDocument`, `CheckState` and `CheckDocument` — covers the other direction: rendering what a run did onto a pull request comment, a check run or the job summary. No `@actions/*` dependency anywhere — the cache, artifact and tool-cache protocols are implemented directly against their HTTP APIs.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/Secret.js

@@ -61,8 +61,7 @@ var Secret = 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
@@ -121,9 +120,8 @@ var Secret = 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
@@ -143,8 +141,7 @@ var Secret = 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
@@ -166,13 +163,10 @@ var Secret = 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
@@ -187,9 +181,8 @@ var Secret = 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.
 	*/

package/ToolInstaller.js

@@ -96,8 +96,8 @@ const make = Effect.gen(function* () {
 	* installed". Discarding it is what makes an extraction failure unactionable.
 	*
 	* **One spawn, not two — load-bearing**, and why is spelled once in
-	* `internal/spawn.ts`: the double run failed 5/5 on real Windows runners
-	* because .NET's `ZipFile.ExtractToDirectory` refuses to overwrite.
+	* `internal/spawn.ts`: a second run fails on Windows because .NET's
+	* `ZipFile.ExtractToDirectory` refuses to overwrite.
 	*/
 	const extractWith = (command, archive) => Effect.gen(function* () {
 		const { output, code } = yield* spawnOnce(spawner, command).pipe(Effect.mapError((cause) => new ToolInstallerError({
@@ -287,7 +287,7 @@ const dies = unstubbed("ToolInstaller.makeTest");
 * environment because a double has no `ActionEnvironment` to ask. The literal
 * `/tmp/runner-tool-cache` is what `make`'s `path.join("/tmp", "runner-tool-cache")`
 * spells on POSIX, which is the only place a test double runs. Test-double
-* only; allowlisted as such in `__test__/ambientReads.test.ts`.
+* only.
 */
 const testRoot = () => process.env.RUNNER_TOOL_CACHE ?? "/tmp/runner-tool-cache";
 /**
@@ -323,6 +323,13 @@ const testRoot = () => process.env.RUNNER_TOOL_CACHE ?? "/tmp/runner-tool-cache"
 * @public
 */
 var ToolInstaller = class ToolInstaller extends Context.Service()("@effected/github-actions/ToolInstaller") {
+	/**
+	* 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 layer = Layer.effect(this, make);
 	/**
 	* Where a tool lives in the cache.
@@ -346,9 +353,8 @@ var ToolInstaller = class ToolInstaller extends Context.Service()("@effected/git
 	* 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 makeTest = (overrides = {}) => ({
 		find: () => dies("find"),