@effected/github-actions 0.13.0 → 0.13.2

package/index.d.ts

@@ -1307,20 +1307,30 @@ export declare class CacheKey extends CacheKey_base {
    *
    * @remarks
    * Discovery and matching are **two different jobs**, and separating them is
-   * what makes this testable and correct. The walk is core
-   * `FileSystem.readDirectory(recursive)`; the matching is `@effected/glob`'s
-   * full minimatch dialect — the same dialect `@actions/glob` uses, so a workflow
-   * author's `!**\/node_modules/**` behaves here exactly as it does in every
-   * other cache step in the same workflow. `node:fs.globSync` would have welded
-   * the two together behind one non-stubbable call *and* changed the dialect,
-   * and a dialect divergence surfaces as a silent cache-key difference — the
-   * worst failure mode a cache key has.
-   *
-   * Candidates are matched by their path **relative to the workspace**, which
-   * is what makes "never hash a file outside the workspace" structural rather
-   * than a rule someone has to remember. Directories are excluded: a directory
+   * what makes this testable and correct. The walk is `@effected/walker`'s
+   * `descend`, run once per include from that include's own literal prefix
+   * (a literal include is one `stat`, never a walk) with nothing pruned
+   * implicitly; the matching is `@effected/glob`'s full minimatch dialect —
+   * the same dialect `@actions/glob` uses, so a workflow author's
+   * `!**\/node_modules/**` behaves here exactly as it does in every other
+   * cache step in the same workflow. `node:fs.globSync` would have welded the
+   * two together behind one non-stubbable call *and* changed the dialect, and
+   * a dialect divergence surfaces as a silent cache-key difference — the worst
+   * failure mode a cache key has.
+   *
+   * Candidates are matched by their path **relative to the workspace**, and a
+   * literal that climbs above it (`../lockfile`) is dropped, which is what
+   * makes "never hash a file outside the workspace" structural rather than a
+   * rule someone has to remember. Directories are excluded: a directory
    * called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
-   * would fail rather than being ignored.
+   * would fail rather than being ignored. An absent literal is a miss; any
+   * other failure to read one is a typed `CacheKeyReadError`, because a key
+   * derived from an incomplete file set is wrong in a way nothing reports.
+   *
+   * **One knowing divergence from the runner's `hashFiles()`:** `descend`
+   * never enters a symlinked directory (cycle safety), where `@actions/glob`
+   * follows links by default. A file reachable only through a symlinked
+   * directory does not contribute to the key.
    *
    * The answer is sorted, so a caller cannot make its key depend on the order
    * the filesystem happened to report.
@@ -3428,7 +3438,7 @@ export declare class DetachedProcess {
    * yet, and silently retrying the first is how a misconfigured probe becomes a
    * timeout six seconds later with nothing to show for it.
    */
-  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<void, E | DetachedProcessError, R>;
+  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<undefined, E | DetachedNotReadyError, R>;
   /**
    * A readiness probe over HTTP: `true` when a `GET` answers 2xx.
    *
@@ -3550,15 +3560,6 @@ declare const DryRun_base: Context.ServiceClass<DryRun, "@effected/github-action
  * @public
  */
 export declare class DryRun extends DryRun_base {
-  /**
-   * Driven by the `dry-run` action input, defaulting to a real run.
-   *
-   * @remarks
-   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
-   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
-   * not quietly perform the mutations it meant to rehearse.
-   */
-  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
   /**
    * Driven by a named input.
    *
@@ -3568,6 +3569,15 @@ export declare class DryRun extends DryRun_base {
    * composition site.
    */
   static readonly layerFromInput: (name: string) => Layer.Layer<DryRun, Config.ConfigError>;
+  /**
+   * Driven by the `dry-run` action input, defaulting to a real run.
+   *
+   * @remarks
+   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
+   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
+   * not quietly perform the mutations it meant to rehearse.
+   */
+  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
   /** Driven by an explicit decision the caller has already made. */
   static readonly layerFrom: (enabled: boolean) => Layer.Layer<DryRun>;
   /**
@@ -4130,6 +4140,7 @@ declare const ManagedDocument_base: Schema.Class<ManagedDocument, Schema.Struct<
  * @public
  */
 export declare class ManagedDocument extends ManagedDocument_base {
+  #private;
   /**
    * Read a document out of existing text, or begin a fresh one.
    *
@@ -4216,6 +4227,9 @@ export declare class ManagedDocument extends ManagedDocument_base {
    * synchronous callers can use that variant directly.
    */
   withRegions(entries: ReadonlyArray<readonly [key: string, content: string, meta?: Readonly<Record<string, string>>]>): Effect.Effect<ManagedDocument, ManagedDocumentError>;
+  private scan;
+  /** What every wire key of this document's regions begins with. */
+  private get wirePrefix();
   /** The marker key a region is written under: `namespace.key.region`. */
   private wireKey;
   /** The region key back out of a wire key, for error reporting. */
@@ -4476,9 +4490,11 @@ declare const PackageManagerInstallerError_base: Schema.Class<PackageManagerInst
    * entry). `integrityMismatch` — the downloaded artifact does not hash to
    * what the pin declares; nothing was cached. `integrityMissing` — the pin
    * carries no integrity and the caller asked for `requireIntegrity`.
-   * `unsupportedPlatform` — bun publishes no build for this runner's
-   * OS/architecture pair. `layoutUnexpected` — the artifact extracted, but
-   * its contents are not shaped like the package manager it claims to be.
+   * `unsupportedPlatform` — no build exists for this runner's
+   * OS/architecture pair: bun publishes none, or pnpm 12 ships no
+   * `@pnpm/exe.*` native binary for it. `layoutUnexpected` — the artifact
+   * extracted, but its contents are not shaped like the package manager it
+   * claims to be.
    */
   readonly reason: Schema.Literals<readonly ["downloadFailed", "extractFailed", "integrityMismatch", "integrityMissing", "unsupportedPlatform", "layoutUnexpected", "cacheFailed"]>;
   /** The package manager being installed. */
@@ -4516,10 +4532,14 @@ interface PackageManagerInstallOptions {
   readonly requireIntegrity?: boolean | undefined;
   /**
    * The npm registry host the npm, pnpm and yarn tarballs download from.
-   * Defaults to `https://registry.npmjs.org`; a corporate mirror that serves
-   * the standard `/<name>/-/<basename>-<version>.tgz` tarball routes works
-   * unchanged. bun does not ship through a registry — its per-platform zip
-   * always comes from GitHub releases.
+   * Defaults to `https://registry.npmjs.org`. A corporate mirror qualifies
+   * when it serves the standard `/<name>/-/<basename>-<version>.tgz` tarball
+   * route and — for pnpm 12 and later, whose native binary is a second
+   * artifact verified against the registry's own integrity — the
+   * `/<name>/<version>` packument route as JSON carrying `dist.integrity`.
+   * A tarball-only proxy fails a pnpm 12 pin with `downloadFailed` naming
+   * that packument url. bun does not ship through a registry — its
+   * per-platform zip always comes from GitHub releases.
    */
   readonly registry?: string | undefined;
   /**
@@ -4586,10 +4606,14 @@ declare const CachedPackageManager_base: Schema.Class<CachedPackageManager, Sche
  * on Windows); for bun it is the entry directory itself, because the cached
  * `bun` binary is directly executable and a shim would add nothing but a
  * fork. `bins` still maps each published bin name to the underlying entry —
- * a Node script to run with `node` for npm/pnpm/yarn, the native binary for
- * bun. Calling `addPath` remains deliberately the consumer's move, and note
- * that `addPath` targets *subsequent* steps: a same-process probe must use
- * the absolute paths in `bins` or `binDir`.
+ * a Node script to run with `node` for npm, yarn and pnpm 11 and earlier; an
+ * executable to run directly for bun and for pnpm 12+, whose `pnpm` is the
+ * host's native binary (overlaid onto the cached wrapper the way pnpm's own
+ * install script does) and whose `pn`/`pnpx`/`pnx` are shell aliases of it.
+ * Each shim already applies that distinction. Calling `addPath` remains
+ * deliberately the consumer's move, and note that `addPath` targets
+ * *subsequent* steps: a same-process probe must use the absolute paths in
+ * `bins` or `binDir`.
  *
  * @public
  */

package/internal/actionsResults.js

@@ -1,3 +1,4 @@
+import { payloadOf } from "./jwt.js";
 import { Effect, Option, Redacted, Result } from "effect";
 
 //#region src/internal/actionsResults.ts
@@ -18,20 +19,13 @@ const RESULTS_URL = "ACTIONS_RESULTS_URL";
 /** The variable holding the run-scoped credential. Absent outside a `uses:` step. */
 const RUNTIME_TOKEN = "ACTIONS_RUNTIME_TOKEN";
 /**
-* Decode a JWT payload segment.
+* The `misconfigured` detail every results-backend consumer reports when
+* {@link resultsBackend} fails: names the missing variable, and says why it is
+* missing — the single most common misuse of these services.
 *
-* @remarks
-* No signature verification, deliberately and for the same reason
-* `OidcTokenIssuer` gives: the token was handed to this process by the runner
-* that started it, and the claim read here scopes a request rather than
-* authorizing one.
+* @internal
 */
-const payloadOf = (token) => {
-	const segments = token.split(".");
-	if (segments.length !== 3) throw new Error(`expected a three-segment JWT, got ${segments.length}`);
-	const json = Buffer.from(segments[1] ?? "", "base64url").toString("utf8");
-	return JSON.parse(json);
-};
+const misconfiguredDetail = (variable, service) => `${variable} is not set — the ${service} is only reachable from a \`uses:\` step, never from \`run:\``;
 /**
 * The run and job ids the artifact protocol needs, from the runtime token's
 * `scp` claim.
@@ -44,13 +38,9 @@ const payloadOf = (token) => {
 * @internal
 */
 const backendIdsFrom = (token) => {
-	let payload;
-	try {
-		payload = payloadOf(token);
-	} catch (cause) {
-		return Result.fail(`the runtime token is not a readable JWT: ${cause instanceof Error ? cause.message : cause}`);
-	}
-	const scope = payload.scp;
+	const payload = payloadOf(token);
+	if (Result.isFailure(payload)) return Result.fail(`the runtime token is not a readable JWT: ${payload.failure.detail}`);
+	const scope = payload.success?.scp;
 	if (typeof scope !== "string") return Result.fail("the runtime token carries no `scp` claim");
 	for (const entry of scope.split(" ")) {
 		const parts = entry.split(":");
@@ -95,4 +85,4 @@ const resultsBackend = (env) => Effect.gen(function* () {
 });
 
 //#endregion
-export { RESULTS_URL, RUNTIME_TOKEN, backendIdsFrom, resultsBackend };
+export { RESULTS_URL, RUNTIME_TOKEN, backendIdsFrom, misconfiguredDetail, resultsBackend };

package/internal/cacheService.js

@@ -0,0 +1,70 @@
+import { CONFLICT, isOk, stringField } from "./twirp.js";
+import { Effect, Option } from "effect";
+
+//#region src/internal/cacheService.ts
+/**
+* The Actions `CacheService` choreography — reserve, upload, finalize; look up
+* — spelled once for the two services that speak it.
+*
+* @remarks
+* `ActionCache` files a tar archive under a path-derived version and
+* `BlobStore.githubCache` files an envelope under a constant one, but the
+* three RPCs between them and their conflict semantics are identical. Each
+* caller supplies its own per-key `call` and its own `refused` constructor, so
+* the errors stay the caller's; this module owns only the protocol. It reaches
+* `effect` and the Twirp client and nothing heavier — the Azure transfer of
+* the bytes between the two RPCs stays in the three modules licensed to import
+* it (`__test__/reachability.test.ts`).
+*
+* @internal
+*/
+/** The Twirp service the Actions cache protocol lives under. @internal */
+const CACHE_SERVICE = "github.actions.results.api.v1.CacheService";
+/**
+* Reserve `(key, version)` for an upload. `Option.none()` means another job
+* saved this key first — entries are immutable, so the cache already holds
+* what the caller wanted and there is nothing left to do.
+*
+* @internal
+*/
+const reserveUpload = (client, key, version) => Effect.flatMap(client.call("CreateCacheEntry", {
+	key,
+	version
+}), (created) => {
+	if (created === CONFLICT) return Effect.succeedNone;
+	const url = stringField(created, "signedUploadUrl");
+	return !isOk(created) || url === void 0 ? Effect.fail(client.refused("CreateCacheEntry returned no upload url")) : Effect.succeedSome(url);
+});
+/**
+* Confirm an upload. Not folded in with the reservation: an unfinalized upload
+* leaves bytes in Azure that no lookup can reach — a silent no-op that reads
+* as a successful save — so it is a failure even though every byte arrived.
+*
+* @internal
+*/
+const finalizeUpload = (client, key, version, sizeBytes) => Effect.flatMap(client.call("FinalizeCacheEntryUpload", {
+	key,
+	version,
+	size_bytes: String(sizeBytes)
+}), (finalized) => finalized === CONFLICT || !isOk(finalized) ? Effect.fail(client.refused("FinalizeCacheEntryUpload did not confirm the upload")) : Effect.void);
+/**
+* The signed download url for a key, walking the restore-key ladder.
+* `Option.none()` is a miss, not a failure — a cold cache is the normal state.
+*
+* @internal
+*/
+const lookupDownload = (client, key, restoreKeys, version) => Effect.map(client.call("GetCacheEntryDownloadURL", {
+	key,
+	restore_keys: [...restoreKeys],
+	version
+}), (found) => {
+	if (found === CONFLICT || !isOk(found)) return Option.none();
+	const url = stringField(found, "signedDownloadUrl");
+	return url === void 0 ? Option.none() : Option.some({
+		url,
+		matchedKey: stringField(found, "matchedKey")
+	});
+});
+
+//#endregion
+export { CACHE_SERVICE, finalizeUpload, lookupDownload, reserveUpload };

package/internal/digest.js

@@ -0,0 +1,42 @@
+import { Effect, Encoding, Stream } from "effect";
+import { createHash } from "node:crypto";
+
+//#region src/internal/digest.ts
+/**
+* The sanctioned `node:crypto` digests, spelled once.
+*
+* @remarks
+* Core `Crypto` is RNG-only — no digest, no HMAC — so this package's licence
+* for a `node:` import covers hashing (`CLAUDE.md`). Keeping every `createHash`
+* behind this module is what makes that licence auditable in one place rather
+* than six, and keeps the streamed file digest — the shape a multi-gigabyte
+* toolchain archive needs — from being re-derived per caller.
+*
+* @internal
+*/
+/** The raw SHA-256 of a string or byte array held in memory. @internal */
+const sha256 = (value) => new Uint8Array(createHash("sha256").update(value).digest());
+/** The hex SHA-256 of a string or byte array held in memory. @internal */
+const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
+/**
+* The raw digest of a file's bytes under `algorithm`, streamed rather than
+* buffered. Raw, because a caller that folds several file digests into one
+* (`CacheKey.hashFiles`, byte-compatible with the runner's `hashFiles()`)
+* hashes the digest BYTES, not their hex spelling.
+*
+* `algorithm` must be one `node:crypto` supports — every caller's grammar
+* admits only `sha1`/`sha256`/`sha384`/`sha512`, so `createHash` cannot throw.
+*
+* @internal
+*/
+const digestFile = (fs, file, algorithm) => Effect.suspend(() => {
+	const accumulator = createHash(algorithm);
+	return Stream.runForEach(fs.stream(file), (chunk) => Effect.sync(() => {
+		accumulator.update(chunk);
+	})).pipe(Effect.map(() => new Uint8Array(accumulator.digest())));
+});
+/** {@link digestFile}, as hex. @internal */
+const digestFileHex = (fs, file, algorithm) => Effect.map(digestFile(fs, file, algorithm), Encoding.encodeHex);
+
+//#endregion
+export { digestFile, digestFileHex, sha256, sha256Hex };

package/internal/fsProbe.js

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+
+//#region src/internal/fsProbe.ts
+/**
+* The entry's type, or `undefined` when nothing readable is there. Absence
+* and unreadability collapse together on purpose: every caller's next move
+* (reinstall, write the shim, fail `layoutUnexpected`) is the same for both.
+*
+* @internal
+*/
+const typeAt = (fs, path) => Effect.map(Effect.option(fs.stat(path)), (info) => info._tag === "Some" ? info.value.type : void 0);
+
+//#endregion
+export { typeAt };

package/internal/jwt.js

@@ -0,0 +1,63 @@
+import { Encoding, Result } from "effect";
+
+//#region src/internal/jwt.ts
+/**
+* The JWT segment codec — read a payload, or frame an unsigned token — for the
+* two places this package reads a runner-issued token's claims.
+*
+* @remarks
+* **No signature verification, deliberately.** Every token read here was
+* handed to this process by the runner that started it, and the claim read
+* scopes a request (`actionsResults`) or is republished for a verifier
+* elsewhere (`OidcTokenIssuer`); neither authorizes anything on the strength
+* of the claim alone. Do not "fix" it here.
+*
+* Core `Encoding` does the base64url work, so no `Buffer` is involved: it is
+* strict about the alphabet where Node's decoder is forgiving, which is why
+* there is a test whose payload actually contains `-` and `_`.
+*
+* @internal
+*/
+/**
+* The decoded payload of `token` — the middle segment, base64url JSON —
+* without any check on the signature.
+*
+* @internal
+*/
+const payloadOf = (token) => {
+	const segments = token.split(".");
+	const payload = segments[1];
+	if (segments.length !== 3 || payload === void 0 || payload === "") return Result.fail({
+		kind: "segments",
+		detail: `expected three segments, got ${segments.length}`
+	});
+	const json = Encoding.decodeBase64UrlString(payload);
+	if (Result.isFailure(json)) return Result.fail({
+		kind: "payload",
+		detail: "the payload is not base64url JSON",
+		cause: json.failure
+	});
+	try {
+		return Result.succeed(JSON.parse(json.success));
+	} catch (cause) {
+		return Result.fail({
+			kind: "payload",
+			detail: "the payload is not base64url JSON",
+			cause
+		});
+	}
+};
+/**
+* An **unsigned** JWT: `header.payload.unsigned`, each JSON segment
+* base64url-encoded. For building test doubles and nothing else — the
+* signature segment is a placeholder, so this token fails any verifier.
+*
+* @internal
+*/
+const unsignedJwt = (header, payload) => {
+	const segment = (value) => Encoding.encodeBase64Url(JSON.stringify(value));
+	return `${segment(header)}.${segment(payload)}.unsigned`;
+};
+
+//#endregion
+export { payloadOf, unsignedJwt };

package/internal/pnpmExe.js

@@ -0,0 +1,124 @@
+import { Encoding, Option, Result } from "effect";
+
+//#region src/internal/pnpmExe.ts
+/**
+* The pnpm native-binary layout: from pnpm 12 the `pnpm` registry package is a
+* thin wrapper whose `pnpm` bin is a shebang-less placeholder that the
+* package's own install script overwrites with the host's native executable,
+* fetched as an optional dependency named `@pnpm/exe.<os>-<arch>[-musl]`.
+* The installer never runs lifecycle scripts, so it performs that overlay
+* itself; the pure pieces of that live here, where they are testable without
+* a tarball.
+*
+* Detection is by LAYOUT (the manifest's `optionalDependencies` naming an
+* `@pnpm/exe.*` package), never by major version — pnpm 11 and earlier ship
+* no such dependency and keep their Node entry points.
+*
+* @internal
+*/
+/** The prefix every native-binary package name carries. @internal */
+const PNPM_EXE_PREFIX = "@pnpm/exe.";
+/**
+* The targets pnpm publishes a native binary for — the `PLATFORMS` table of
+* the wrapper's own `native-binary.mjs`, flattened to the spellings that
+* follow the prefix. Only linux x64/arm64 have a musl twin.
+*/
+const PNPM_EXE_TARGETS = /* @__PURE__ */ new Set([
+	"linux-x64",
+	"linux-arm64",
+	"linux-x64-musl",
+	"linux-arm64-musl",
+	"linux-riscv64",
+	"linux-ppc64",
+	"linux-s390x",
+	"darwin-x64",
+	"darwin-arm64",
+	"win32-x64",
+	"win32-arm64",
+	"freebsd-x64",
+	"android-x64",
+	"android-arm64"
+]);
+/** `RUNNER_OS` spellings (lower-cased) onto Node's `process.platform` spellings, which the targets use. */
+const RUNNER_OS_TO_PLATFORM = {
+	linux: "linux",
+	macos: "darwin",
+	windows: "win32"
+};
+/**
+* The `@pnpm/exe.*` target for a runner platform, or `None` when pnpm
+* publishes no native binary for it.
+*
+* `musl` only distinguishes on linux; an arch released for glibc alone
+* (riscv64, ppc64, s390x) answers `None` on a musl host, as upstream does —
+* the glibc binary cannot run there.
+*
+* @internal
+*/
+const pnpmExeTarget = (runnerOs, arch, musl) => {
+	const platform = RUNNER_OS_TO_PLATFORM[runnerOs.toLowerCase()];
+	if (platform === void 0) return Option.none();
+	const target = `${platform}-${arch}${platform === "linux" && musl ? "-musl" : ""}`;
+	return PNPM_EXE_TARGETS.has(target) ? Option.some(target) : Option.none();
+};
+/**
+* Whether the HOST libc is musl, the way the wrapper's `native-binary.mjs`
+* decides it: a glibc build of node reports `glibcVersionRuntime` in its
+* diagnostic report header, a musl build does not. Only meaningful on a
+* linux host; anything unprobeable counts as glibc, which is what every
+* hosted runner is.
+*
+* `process.report` is a global, not a `node:` import, so this stays inside
+* the package's closed `node:` list.
+*
+* @internal
+*/
+const detectMusl = () => {
+	if (process.platform !== "linux") return false;
+	try {
+		const report = process.report?.getReport();
+		if (report === void 0 || report.header === void 0) return false;
+		return report.header.glibcVersionRuntime === void 0 || report.header.glibcVersionRuntime === "";
+	} catch {
+		return false;
+	}
+};
+/** The SRI algorithms a registry may list, strongest first. */
+const SRI_ALGORITHMS = [
+	"sha512",
+	"sha384",
+	"sha256",
+	"sha1"
+];
+/**
+* The strongest entry of a Subresource Integrity string (`<algo>-<base64>`,
+* several separated by whitespace), as `{ algorithm, hex }` — the spelling a
+* corepack pin uses, so a mismatch reports both sides the same way. `None`
+* when nothing parseable is there.
+*
+* @internal
+*/
+const strongestSri = (integrity) => {
+	const entries = integrity.split(/\s+/).filter((entry) => entry.length > 0).flatMap((entry) => {
+		const dash = entry.indexOf("-");
+		if (dash <= 0) return [];
+		const algorithm = entry.slice(0, dash).toLowerCase();
+		if (!SRI_ALGORITHMS.includes(algorithm)) return [];
+		const digest = entry.slice(dash + 1).split("?")[0] ?? "";
+		const decoded = Encoding.decodeBase64(digest);
+		return Result.isSuccess(decoded) ? [{
+			algorithm,
+			hex: Encoding.encodeHex(decoded.success)
+		}] : [];
+	});
+	for (const algorithm of SRI_ALGORITHMS) {
+		const found = entries.find((entry) => entry.algorithm === algorithm);
+		if (found !== void 0) return Option.some(found);
+	}
+	return Option.none();
+};
+/** Whether a bin target is a Node script (run with `node`) rather than an executable run directly. @internal */
+const isNodeScript = (target) => /\.[cm]?js$/i.test(target);
+
+//#endregion
+export { PNPM_EXE_PREFIX, detectMusl, isNodeScript, pnpmExeTarget, strongestSri };

package/internal/runner.js

@@ -0,0 +1,31 @@
+import { Effect, Option } from "effect";
+
+//#region src/internal/runner.ts
+/**
+* Whether `RUNNER_OS` says Windows. `false` when unset — off a runner, the
+* POSIX shape is the honest default.
+*
+* @internal
+*/
+const isWindowsRunner = (env) => Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
+	onNone: () => false,
+	onSome: (os) => os.toLowerCase() === "windows"
+}));
+/**
+* The tool-cache root: `RUNNER_TOOL_CACHE`, or `/tmp/runner-tool-cache` off a
+* runner.
+*
+* @remarks
+* Resolved at layer construction, never at import: the source package read
+* the variable into a module-level constant, which fixed the root before any
+* layer could say otherwise and made it impossible to point a test elsewhere.
+* `PackageManagerInstaller` resolves the same root because the shims it
+* writes into a staged entry must name the FINAL cache path; sharing the
+* resolution is what keeps its post-swap equality check a formality.
+*
+* @internal
+*/
+const toolCacheRoot = (env, path) => Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
+
+//#endregion
+export { isWindowsRunner, toolCacheRoot };

package/internal/runnerFile.js

@@ -0,0 +1,45 @@
+//#region src/internal/runnerFile.ts
+/**
+* The runner-file heredoc protocol — `GITHUB_OUTPUT`, `GITHUB_ENV` and
+* `GITHUB_STATE` all take `name<<DELIM\nvalue\nDELIM\n` — spelled once for
+* `ActionOutputs` and `ActionState`.
+*
+* @remarks
+* **Delimiters are derived, never random.** GitHub's own toolkit uses a
+* random UUID here and accepts the (tiny) chance of collision. Deriving the
+* delimiter instead makes collision **impossible** rather than improbable,
+* needs no randomness — so no `Crypto` in `R` and no unreproducible output —
+* and is trivially testable. A value that contains a delimiter would
+* terminate its block early and corrupt every entry after it, which is a
+* value-controlled injection into the runner's own file.
+*
+* @internal
+*/
+/** The base delimiter for a heredoc block. */
+const BASE_DELIMITER = "EFFECTED_EOF";
+/** A delimiter guaranteed absent from `value`. @internal */
+const delimiterFor = (value) => {
+	let delimiter = BASE_DELIMITER;
+	while (value.includes(delimiter)) delimiter = `${delimiter}_`;
+	return delimiter;
+};
+/**
+* Whether `name` can head a block without breaking the structure it lives
+* in: non-empty, and free of the line breaks that would end it early.
+*
+* @internal
+*/
+const isUsableName = (name) => name !== "" && !/[\r\n]/.test(name);
+/**
+* One heredoc block, ready to append. The caller has checked the name with
+* {@link isUsableName}.
+*
+* @internal
+*/
+const heredocBlock = (name, value) => {
+	const delimiter = delimiterFor(value);
+	return `${name}<<${delimiter}\n${value}\n${delimiter}\n`;
+};
+
+//#endregion
+export { delimiterFor, heredocBlock, isUsableName };

package/internal/sigv4.js

@@ -1,4 +1,5 @@
-import { createHash, createHmac } from "node:crypto";
+import { sha256Hex } from "./digest.js";
+import { createHmac } from "node:crypto";
 
 //#region src/internal/sigv4.ts
 /**
@@ -18,7 +19,6 @@ import { createHash, createHmac } from "node:crypto";
 * @internal
 */
 const ALGORITHM = "AWS4-HMAC-SHA256";
-const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
 const hmac = (key, value) => new Uint8Array(createHmac("sha256", key).update(value).digest());
 /**
 * Percent-encode one path segment the way SigV4 requires.
@@ -114,4 +114,4 @@ const sign = (request, credentials) => {
 };
 
 //#endregion
-export { canonicalize, sign, signingKey, uriEncode };
+export { canonicalize, sha256Hex as digestHex, sign, signingKey, uriEncode };

package/internal/spawn.js

@@ -0,0 +1,18 @@
+import { Effect, Stream } from "effect";
+
+//#region src/internal/spawn.ts
+/**
+* Spawn `command` once, drain `stdout`+`stderr`, then read the exit code from
+* the same handle. Never fails on a non-zero exit — that is the caller's
+* policy.
+*/
+const spawnOnce = (spawner, command) => Effect.scoped(Effect.gen(function* () {
+	const handle = yield* spawner.spawn(command);
+	return {
+		output: yield* Stream.mkString(Stream.decodeText(handle.all)),
+		code: yield* handle.exitCode
+	};
+}));
+
+//#endregion
+export { spawnOnce };