@effected/github-actions 0.13.0 → 0.13.1

package/ActionState.js

@@ -1,4 +1,6 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
+import { heredocBlock, isUsableName } from "./internal/runnerFile.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { ActionOutputs } from "./ActionOutputs.js";
 import { Context, Effect, FileSystem, Layer, Option, Schema } from "effect";
 
@@ -43,31 +45,19 @@ const make = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const outputs = yield* ActionOutputs;
 	const write = (key, serialized) => Effect.gen(function* () {
-		const path = yield* env.get("GITHUB_STATE").pipe(Effect.mapError((cause) => new ActionStateError({
+		const writeFailed = (cause) => new ActionStateError({
 			reason: "writeFailed",
 			key,
 			cause
-		})));
-		let delimiter = "EFFECTED_EOF";
-		while (serialized.includes(delimiter)) delimiter = `${delimiter}_`;
-		yield* fs.writeFileString(path, `${key}<<${delimiter}\n${serialized}\n${delimiter}\n`, { flag: "a" }).pipe(Effect.mapError((cause) => new ActionStateError({
-			reason: "writeFailed",
-			key,
-			cause
-		})));
+		});
+		if (!isUsableName(key)) return yield* Effect.fail(writeFailed(/* @__PURE__ */ new Error(`"${key}" cannot name a GITHUB_STATE entry`)));
+		const path = yield* env.get("GITHUB_STATE").pipe(Effect.mapError(writeFailed));
+		yield* fs.writeFileString(path, heredocBlock(key, serialized), { flag: "a" }).pipe(Effect.mapError(writeFailed));
 	});
 	const read = (key, schema) => Effect.gen(function* () {
 		const raw = yield* env.getOptional(stateVariable(key));
 		if (Option.isNone(raw)) return Option.none();
-		const parsed = yield* Effect.try({
-			try: () => JSON.parse(raw.value),
-			catch: (cause) => new ActionStateError({
-				reason: "malformed",
-				key,
-				cause
-			})
-		});
-		const decoded = yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(Effect.mapError((cause) => new ActionStateError({
+		const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(raw.value).pipe(Effect.mapError((cause) => new ActionStateError({
 			reason: "malformed",
 			key,
 			cause
@@ -111,9 +101,7 @@ const make = Effect.gen(function* () {
 		saveSecret: (key, secret) => Effect.flatMap(outputs.setSecret(secret), () => write(key, JSON.stringify(secret)))
 	};
 });
-const unimplemented = (member) => {
-	throw new Error(`ActionState.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("ActionState.makeTest");
 /**
 * State that survives the `pre` → `main` → `post` phase boundary.
 *
@@ -130,10 +118,10 @@ var ActionState = class ActionState extends Context.Service()("@effected/github-
 	static layer = Layer.effect(this, make);
 	/** A test double. Unstubbed members die rather than answering wrongly. */
 	static makeTest = (overrides = {}) => ({
-		save: () => Effect.sync(() => unimplemented("save")),
-		get: () => Effect.sync(() => unimplemented("get")),
-		getOptional: () => Effect.sync(() => unimplemented("getOptional")),
-		saveSecret: () => Effect.sync(() => unimplemented("saveSecret")),
+		save: () => dies("save"),
+		get: () => dies("get"),
+		getOptional: () => dies("getOptional"),
+		saveSecret: () => dies("saveSecret"),
 		...overrides
 	});
 	/** {@link ActionState.makeTest} behind `Layer.succeed`. */

package/Artifact.js

@@ -1,10 +1,13 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { BlobTransferError } from "./BlobTransfer.js";
-import { resultsBackend } from "./internal/actionsResults.js";
-import { CONFLICT, field, isOk, stringField, twirpCall } from "./internal/twirp.js";
-import { Context, Effect, FileSystem, Layer, Option, Path, Result, Schema, Stream } from "effect";
+import { misconfiguredDetail, resultsBackend } from "./internal/actionsResults.js";
+import { CONFLICT, field, isOk, stringField, twirpCall, twirpFailureFields } from "./internal/twirp.js";
+import { digestFileHex } from "./internal/digest.js";
+import { isWindowsRunner } from "./internal/runner.js";
+import { spawnOnce } from "./internal/spawn.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
 import { HttpClient } from "effect/unstable/http";
-import { createHash } from "node:crypto";
 import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
@@ -101,17 +104,6 @@ const azure = {
 		})
 	}).pipe(Effect.asVoid)
 };
-const fromTwirp = (failure, artifact) => failure.kind === "status" ? new ArtifactError({
-	reason: "refused",
-	artifact,
-	detail: failure.method,
-	...failure.status === void 0 ? {} : { status: failure.status }
-}) : new ArtifactError({
-	reason: "unreachable",
-	artifact,
-	detail: `${failure.method} did not answer with a Twirp body`,
-	...failure.cause === void 0 ? {} : { cause: failure.cause }
-});
 /** One row of a `ListArtifacts` answer, read under either field spelling. */
 const toItem = (row) => {
 	const createdAt = stringField(row, "createdAt");
@@ -128,14 +120,11 @@ const make = (transfer) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const env = yield* ActionEnvironment;
-	const windows = yield* Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
-		onNone: () => false,
-		onSome: (os) => os.toLowerCase() === "windows"
-	}));
+	const windows = yield* isWindowsRunner(env);
 	const backend = (artifact) => resultsBackend(env).pipe(Effect.mapError((name) => new ArtifactError({
 		reason: "misconfigured",
 		artifact,
-		detail: `${name} is not set — the artifact service is only reachable from a \`uses:\` step, never from \`run:\``
+		detail: misconfiguredDetail(name, "artifact service")
 	})), Effect.flatMap((resolved) => Result.isFailure(resolved.backendIds) ? Effect.fail(new ArtifactError({
 		reason: "misconfigured",
 		artifact,
@@ -157,25 +146,24 @@ const make = (transfer) => Effect.gen(function* () {
 				...ids,
 				...body(ids)
 			}
-		}).pipe(Effect.mapError((failure) => fromTwirp(failure, artifact)));
+		}).pipe(Effect.mapError((failure) => new ArtifactError({
+			...twirpFailureFields(failure),
+			artifact
+		})));
 	});
 	const listAll = (artifact) => Effect.map(call("ListArtifacts", () => ({}), artifact), (answer) => {
 		if (answer === CONFLICT) return [];
 		const rows = field(answer, "artifacts");
 		return Array.isArray(rows) ? rows.map(toItem) : [];
 	});
-	/** Run an archiving command, keeping its stderr. */
+	/** Run an archiving command ONCE (`internal/spawn.ts`), keeping its stderr. */
 	const archive = (command, artifact) => Effect.gen(function* () {
-		const output = yield* spawner.string(command, { includeStderr: true }).pipe(Effect.mapError((cause) => new ArtifactError({
+		const { output, code } = yield* spawnOnce(spawner, command).pipe(Effect.mapError((cause) => new ArtifactError({
 			reason: "archiveFailed",
 			artifact,
 			cause
 		})));
-		if ((yield* spawner.exitCode(command).pipe(Effect.mapError((cause) => new ArtifactError({
-			reason: "archiveFailed",
-			artifact,
-			cause
-		})))) !== 0) return yield* Effect.fail(new ArtifactError({
+		if (code !== 0) return yield* Effect.fail(new ArtifactError({
 			reason: "archiveFailed",
 			artifact,
 			stderr: output.trim()
@@ -197,17 +185,11 @@ const make = (transfer) => Effect.gen(function* () {
 	* payload in this package with no upper bound on size, and a runner has
 	* roughly seven gigabytes of memory for everything.
 	*/
-	const digestOf = (file, artifact) => Effect.gen(function* () {
-		const accumulator = createHash("sha256");
-		yield* Stream.runForEach(fs.stream(file), (chunk) => Effect.sync(() => {
-			accumulator.update(chunk);
-		})).pipe(Effect.mapError((cause) => new ArtifactError({
-			reason: "archiveFailed",
-			artifact,
-			cause
-		})));
-		return accumulator.digest("hex");
-	});
+	const digestOf = (file, artifact) => digestFileHex(fs, file, "sha256").pipe(Effect.mapError((cause) => new ArtifactError({
+		reason: "archiveFailed",
+		artifact,
+		cause
+	})));
 	const moved = (artifact) => Effect.mapError((cause) => new ArtifactError({
 		reason: "transferFailed",
 		artifact,
@@ -351,9 +333,7 @@ const make = (transfer) => Effect.gen(function* () {
 		})
 	};
 });
-const unimplemented = (member) => {
-	throw new Error(`Artifact.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("Artifact.makeTest");
 /**
 * Upload, list, download and delete GitHub Actions artifacts.
 *
@@ -408,11 +388,11 @@ var Artifact = class Artifact extends Context.Service()("@effected/github-action
 	static layerWith = (transfer) => Layer.effect(Artifact, make(transfer));
 	/** A test double. Unstubbed members die rather than reporting an empty run. */
 	static makeTest = (overrides = {}) => ({
-		upload: () => Effect.sync(() => unimplemented("upload")),
-		list: () => Effect.sync(() => unimplemented("list")),
-		get: () => Effect.sync(() => unimplemented("get")),
-		download: () => Effect.sync(() => unimplemented("download")),
-		delete: () => Effect.sync(() => unimplemented("delete")),
+		upload: () => dies("upload"),
+		list: () => dies("list"),
+		get: () => dies("get"),
+		download: () => dies("download"),
+		delete: () => dies("delete"),
 		...overrides
 	});
 	/** {@link Artifact.makeTest} behind `Layer.succeed`. */

package/BlobEnvelope.js

@@ -111,9 +111,9 @@ var BlobEnvelope = class {
 	static version = VERSION;
 	/** Frame metadata and a body into a single blob. */
 	static encodeResult(metadata, body, schema) {
-		const encoded = Schema.encodeUnknownResult(schema)(metadata);
+		const encoded = Schema.encodeUnknownResult(Schema.fromJsonString(schema))(metadata);
 		if (Result.isFailure(encoded)) return Result.fail(new BlobMetadataEncodeError({ cause: encoded.failure }));
-		const metaBytes = new TextEncoder().encode(JSON.stringify(encoded.success));
+		const metaBytes = new TextEncoder().encode(encoded.success);
 		const out = new Uint8Array(HEADER_BYTES + metaBytes.length + body.length);
 		out.set(MAGIC, 0);
 		out[MAGIC.length] = VERSION;
@@ -131,13 +131,7 @@ var BlobEnvelope = class {
 		const metaLength = new DataView(bytes.buffer, bytes.byteOffset).getUint32(MAGIC.length + 1, false);
 		if (bytes.length < HEADER_BYTES + metaLength) return Result.fail(new TruncatedBlobEnvelopeError({}));
 		const metaText = new TextDecoder().decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + metaLength));
-		let parsed;
-		try {
-			parsed = JSON.parse(metaText);
-		} catch (cause) {
-			return Result.fail(new BlobMetadataDecodeError({ cause }));
-		}
-		const decoded = Schema.decodeUnknownResult(schema)(parsed);
+		const decoded = Schema.decodeUnknownResult(Schema.fromJsonString(schema))(metaText);
 		if (Result.isFailure(decoded)) return Result.fail(new BlobMetadataDecodeError({ cause: decoded.failure }));
 		return Result.succeed({
 			metadata: decoded.success,

package/BlobStore.githubCache.js

@@ -1,17 +1,16 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
 import { BlobTransferError } from "./BlobTransfer.js";
-import { resultsBackend } from "./internal/actionsResults.js";
-import { CONFLICT, isOk, stringField, twirpCall } from "./internal/twirp.js";
+import { misconfiguredDetail, resultsBackend } from "./internal/actionsResults.js";
+import { twirpCall, twirpFailureFields } from "./internal/twirp.js";
+import { CACHE_SERVICE, finalizeUpload, lookupDownload, reserveUpload } from "./internal/cacheService.js";
+import { sha256Hex } from "./internal/digest.js";
 import { BlobEnvelope } from "./BlobEnvelope.js";
 import { BlobStore, BlobStoreError } from "./BlobStore.js";
 import { Effect, Layer, Option } from "effect";
 import { HttpClient } from "effect/unstable/http";
-import { createHash } from "node:crypto";
 import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
 
 //#region src/BlobStore.githubCache.ts
-/** The Twirp service the Actions cache protocol lives under. */
-const SERVICE = "github.actions.results.api.v1.CacheService";
 /**
 * The `version` every entry is filed under.
 *
@@ -25,7 +24,7 @@ const SERVICE = "github.actions.results.api.v1.CacheService";
 * inside the blob, so a framing change is a clean miss rather than a key change
 * that strands every existing entry.
 */
-const VERSION = createHash("sha256").update("blobstore|1.0").digest("hex");
+const VERSION = sha256Hex("blobstore|1.0");
 /**
 * The Azure half, ~15 lines and duplicated on purpose.
 *
@@ -52,40 +51,37 @@ const azure = {
 		})
 	}).pipe(Effect.map((buffer) => new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)))
 };
-const fromTwirp = (failure, key) => failure.kind === "status" ? new BlobStoreError({
-	reason: "refused",
-	key,
-	...failure.status === void 0 ? {} : { status: failure.status }
-}) : new BlobStoreError({
-	reason: "unreachable",
-	key,
-	detail: `${failure.method} answered with something that is not a Twirp body`,
-	...failure.cause === void 0 ? {} : { cause: failure.cause }
-});
 const make = (transfer) => Effect.gen(function* () {
 	const http = yield* HttpClient.HttpClient;
 	const env = yield* ActionEnvironment;
 	const backend = resultsBackend(env).pipe(Effect.mapError((name) => new BlobStoreError({
 		reason: "misconfigured",
-		detail: `${name} is not set — the Actions results backend is only reachable from a \`uses:\` step, never from \`run:\``
+		detail: misconfiguredDetail(name, "Actions results backend")
 	})));
-	const call = (method, body, key) => Effect.gen(function* () {
-		const { baseUrl, token } = yield* backend;
-		return yield* twirpCall({
-			http,
-			baseUrl,
-			service: SERVICE,
-			token,
-			method,
-			body
-		}).pipe(Effect.mapError((failure) => fromTwirp(failure, key)));
+	/** The cache service, for one key: every failure names it. */
+	const cacheService = (key) => ({
+		call: (method, body) => Effect.gen(function* () {
+			const { baseUrl, token } = yield* backend;
+			return yield* twirpCall({
+				http,
+				baseUrl,
+				service: CACHE_SERVICE,
+				token,
+				method,
+				body
+			}).pipe(Effect.mapError((failure) => new BlobStoreError({
+				...twirpFailureFields(failure),
+				key
+			})));
+		}),
+		refused: (detail) => new BlobStoreError({
+			reason: "refused",
+			key,
+			detail
+		})
 	});
 	/** The signed download url for a key, or nothing — a miss is not a failure. */
-	const download = (key) => Effect.map(call("GetCacheEntryDownloadURL", {
-		key,
-		restore_keys: [],
-		version: VERSION
-	}, key), (answer) => answer === CONFLICT || !isOk(answer) ? Option.none() : Option.fromNullishOr(stringField(answer, "signedDownloadUrl")));
+	const download = (key) => Effect.map(lookupDownload(cacheService(key), key, [], VERSION), Option.map((hit) => hit.url));
 	const moved = (key) => Effect.mapError((cause) => new BlobStoreError({
 		reason: "unreachable",
 		key,
@@ -100,28 +96,11 @@ const make = (transfer) => Effect.gen(function* () {
 		}),
 		put: (key, blob, schema) => Effect.gen(function* () {
 			const framed = yield* Effect.fromResult(BlobEnvelope.encodeResult(blob.metadata, blob.body, schema));
-			const created = yield* call("CreateCacheEntry", {
-				key,
-				version: VERSION
-			}, key);
-			if (created === CONFLICT) return;
-			const url = stringField(created, "signedUploadUrl");
-			if (!isOk(created) || url === void 0) return yield* Effect.fail(new BlobStoreError({
-				reason: "refused",
-				key,
-				detail: "CreateCacheEntry returned no upload url"
-			}));
-			yield* transfer.uploadData(url, framed).pipe(moved(key));
-			const finalized = yield* call("FinalizeCacheEntryUpload", {
-				key,
-				version: VERSION,
-				size_bytes: String(framed.byteLength)
-			}, key);
-			if (finalized === CONFLICT || !isOk(finalized)) return yield* Effect.fail(new BlobStoreError({
-				reason: "refused",
-				key,
-				detail: "FinalizeCacheEntryUpload did not confirm the upload"
-			}));
+			const service = cacheService(key);
+			const url = yield* reserveUpload(service, key, VERSION);
+			if (Option.isNone(url)) return;
+			yield* transfer.uploadData(url.value, framed).pipe(moved(key));
+			yield* finalizeUpload(service, key, VERSION, framed.byteLength);
 		}),
 		has: (key) => Effect.map(download(key), Option.isSome)
 	};

package/BlobStore.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { BlobEnvelope } from "./BlobEnvelope.js";
 import { sign } from "./internal/sigv4.js";
 import { Secret } from "./Secret.js";
@@ -85,9 +86,9 @@ var BlobStore = class BlobStore extends Context.Service()("@effected/github-acti
 	static layerS3 = (config) => Layer.effect(BlobStore, makeS3(config));
 	/** A test double. Unstubbed members die rather than reporting a miss. */
 	static makeTest = (overrides = {}) => ({
-		get: () => Effect.sync(() => unimplemented("get")),
-		put: () => Effect.sync(() => unimplemented("put")),
-		has: () => Effect.sync(() => unimplemented("has")),
+		get: () => dies("get"),
+		put: () => dies("put"),
+		has: () => dies("has"),
 		...overrides
 	});
 	/** {@link BlobStore.makeTest} behind `Layer.succeed`. */
@@ -115,9 +116,7 @@ var BlobStore = class BlobStore extends Context.Service()("@effected/github-acti
 		};
 	});
 };
-const unimplemented = (member) => {
-	throw new Error(`BlobStore.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("BlobStore.makeTest");
 const makeS3 = (config) => Effect.gen(function* () {
 	const http = yield* HttpClient.HttpClient;
 	let endpoint = config.endpoint ?? `https://s3.${config.region}.amazonaws.com`;
@@ -161,15 +160,17 @@ const makeS3 = (config) => Effect.gen(function* () {
 			cause
 		})));
 	});
+	/** Anything outside 2xx is the store refusing; a caller reads `404` first where a miss is an answer. */
+	const accepted = (key, status) => status < 200 || status >= 300 ? Effect.fail(new BlobStoreError({
+		reason: "refused",
+		key,
+		status
+	})) : Effect.void;
 	return {
 		get: (key, schema) => Effect.gen(function* () {
 			const response = yield* send("GET", key, /* @__PURE__ */ new Uint8Array(0));
 			if (response.status === 404) return Option.none();
-			if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new BlobStoreError({
-				reason: "refused",
-				key,
-				status: response.status
-			}));
+			yield* accepted(key, response.status);
 			const buffer = yield* response.arrayBuffer.pipe(Effect.mapError((cause) => new BlobStoreError({
 				reason: "unreachable",
 				key,
@@ -180,20 +181,12 @@ const makeS3 = (config) => Effect.gen(function* () {
 		put: (key, blob, schema) => Effect.gen(function* () {
 			const framed = yield* Effect.fromResult(BlobEnvelope.encodeResult(blob.metadata, blob.body, schema));
 			const response = yield* send("PUT", key, framed);
-			if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new BlobStoreError({
-				reason: "refused",
-				key,
-				status: response.status
-			}));
+			yield* accepted(key, response.status);
 		}),
 		has: (key) => Effect.gen(function* () {
 			const response = yield* send("HEAD", key, /* @__PURE__ */ new Uint8Array(0));
 			if (response.status === 404) return false;
-			if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new BlobStoreError({
-				reason: "refused",
-				key,
-				status: response.status
-			}));
+			yield* accepted(key, response.status);
 			return true;
 		})
 	};

package/CacheKey.js

@@ -1,6 +1,7 @@
+import { sha256, sha256Hex } from "./internal/digest.js";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
-import { createHash } from "node:crypto";
 import { GlobSet } from "@effected/glob";
+import { descend } from "@effected/walker";
 
 //#region src/CacheKey.ts
 /**
@@ -257,9 +258,11 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 	* state.
 	*/
 	static forBranch(options) {
-		const segments = [];
-		if (options.os !== void 0) segments.push(options.os);
-		segments.push(options.scope, options.branch);
+		const segments = options.os === void 0 ? [options.scope, options.branch] : [
+			options.os,
+			options.scope,
+			options.branch
+		];
 		if (options.hash !== void 0) segments.push(options.hash);
 		return CacheKey.make({ segments });
 	}
@@ -302,7 +305,7 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 	*/
 	static digest(input, length = 8) {
 		if (!Number.isInteger(length) || length < 1 || length > 64) throw new RangeError(`A digest length must be an integer between 1 and 64, got ${length}`);
-		return createHash("sha256").update(input).digest("hex").slice(0, length);
+		return sha256Hex(input).slice(0, length);
 	}
 	/**
 	* Hash a set of files into a single digest.
@@ -330,30 +333,38 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 		const digests = yield* Effect.all(ordered.map((path) => fs.readFile(path).pipe(Effect.mapError((cause) => new CacheKeyReadError({
 			path,
 			cause
-		})), Effect.map((bytes) => createHash("sha256").update(bytes).digest()))), { concurrency: 8 });
-		const accumulator = createHash("sha256");
-		for (const digest of digests) accumulator.update(digest);
-		return Option.some(accumulator.digest("hex"));
+		})), Effect.map(sha256))), { concurrency: 8 });
+		return Option.some(sha256Hex(Uint8Array.from(digests.flatMap((digest) => [...digest]))));
 	});
 	/**
 	* Every file under `workspace` that the pattern set matches.
 	*
 	* @remarks
 	* Discovery and matching are **two different jobs**, and separating them is
-	* what makes this testable and correct. The walk is core
-	* `FileSystem.readDirectory(recursive)`; the matching is `@effected/glob`'s
-	* full minimatch dialect — the same dialect `@actions/glob` uses, so a workflow
-	* author's `!**\/node_modules/**` behaves here exactly as it does in every
-	* other cache step in the same workflow. `node:fs.globSync` would have welded
-	* the two together behind one non-stubbable call *and* changed the dialect,
-	* and a dialect divergence surfaces as a silent cache-key difference — the
-	* worst failure mode a cache key has.
-	*
-	* Candidates are matched by their path **relative to the workspace**, which
-	* is what makes "never hash a file outside the workspace" structural rather
-	* than a rule someone has to remember. Directories are excluded: a directory
+	* 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.
@@ -361,24 +372,38 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 	static matchingFiles = Effect.fn("CacheKey.matchingFiles")(function* (options) {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
+		const { workspace } = options;
 		const set = yield* GlobSet.compile(options.patterns).pipe(Effect.mapError((cause) => new CacheKeyBadPatternError({
 			pattern: cause.pattern,
 			cause
 		})));
-		const entries = yield* fs.readDirectory(options.workspace, { recursive: true }).pipe(Effect.mapError((cause) => new CacheKeyReadError({
-			path: options.workspace,
+		yield* fs.stat(workspace).pipe(Effect.mapError((cause) => new CacheKeyReadError({
+			path: workspace,
 			cause
 		})));
-		const matched = [];
-		for (const entry of entries) {
-			if (!set.matches(entry.replaceAll("\\", "/"))) continue;
-			const absolute = path.join(options.workspace, entry);
-			if ((yield* fs.stat(absolute).pipe(Effect.mapError((cause) => new CacheKeyReadError({
-				path: absolute,
+		const candidates = /* @__PURE__ */ new Set();
+		for (const literal of set.literals) {
+			const target = path.join(workspace, literal);
+			const relative = path.relative(workspace, target);
+			if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) continue;
+			const info = yield* fs.stat(target).pipe(Effect.map(Option.some), Effect.catchIf((error) => error.reason._tag === "NotFound", () => Effect.succeedNone), Effect.mapError((cause) => new CacheKeyReadError({
+				path: target,
+				cause
+			})));
+			if (Option.isSome(info) && info.value.type === "File") candidates.add(literal);
+		}
+		for (const wildcard of set.wildcards) {
+			if (wildcard.negated) continue;
+			const found = yield* descend(wildcard, {
+				cwd: workspace,
+				prune: []
+			}).pipe(Effect.mapError((cause) => new CacheKeyReadError({
+				path: path.join(workspace, cause.path),
 				cause
-			})))).type === "File") matched.push(absolute);
+			})));
+			for (const match of found) candidates.add(match);
 		}
-		return matched.sort();
+		return [...candidates].filter((candidate) => set.matches(candidate)).sort().map((candidate) => path.join(workspace, candidate));
 	});
 	/**
 	* Hash every file under `workspace` that the pattern set matches.

package/CheckDocument.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { CheckState } from "./CheckState.js";
 import { ManagedDocument } from "./ManagedDocument.js";
 import { Clock, Context, Duration, Effect, Latch, Layer, Ref, Schema, Semaphore } from "effect";
@@ -28,6 +29,12 @@ var CheckReport = class extends Schema.Class("CheckReport")({
 	/** Where the check's name should link. */
 	url: Schema.optionalKey(Schema.String)
 }) {};
+/** What each {@link CheckDocumentError} kind reads as. */
+const KIND_PROSE = {
+	render: "The check document could not be regenerated from the reported state",
+	read: "Reading the check document's current text failed",
+	sink: "Writing the check document failed"
+};
 /**
 * Raised when the check document cannot be regenerated, read back or written.
 *
@@ -53,7 +60,7 @@ var CheckDocumentError = class extends Schema.TaggedError()("CheckDocumentError"
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
-		return this.kind === "render" ? "The check document could not be regenerated from the reported state" : this.kind === "read" ? "Reading the check document's current text failed" : "Writing the check document failed";
+		return KIND_PROSE[this.kind];
 	}
 };
 /**
@@ -90,12 +97,13 @@ var CheckDocumentStamp = class extends Schema.Class("CheckDocumentStamp")({
 		return compareRunId(incoming.runId, existing.runId) >= 0;
 	}
 };
+/** A total order over two comparable values. */
+const order = (left, right) => left === right ? 0 : left < right ? -1 : 1;
 /** Epoch order when both sides parse as dates, lexical otherwise. */
 const compareAt = (left, right) => {
 	const leftEpoch = Date.parse(left);
 	const rightEpoch = Date.parse(right);
-	if (!Number.isNaN(leftEpoch) && !Number.isNaN(rightEpoch)) return leftEpoch === rightEpoch ? 0 : leftEpoch < rightEpoch ? -1 : 1;
-	return left === right ? 0 : left < right ? -1 : 1;
+	return Number.isNaN(leftEpoch) || Number.isNaN(rightEpoch) ? order(left, right) : order(leftEpoch, rightEpoch);
 };
 /**
 * Numeric order when both sides are non-blank finite numbers, lexical
@@ -112,9 +120,9 @@ const compareRunId = (left, right) => {
 	if (left.trim() !== "" && right.trim() !== "") {
 		const leftNumber = Number(left);
 		const rightNumber = Number(right);
-		if (Number.isFinite(leftNumber) && Number.isFinite(rightNumber)) return leftNumber === rightNumber ? 0 : leftNumber < rightNumber ? -1 : 1;
+		if (Number.isFinite(leftNumber) && Number.isFinite(rightNumber)) return order(leftNumber, rightNumber);
 	}
-	return left === right ? 0 : left < right ? -1 : 1;
+	return order(left, right);
 };
 /** The stamp a document's own regions carry, when they carry one. */
 const stampOf = (meta) => {
@@ -293,16 +301,15 @@ var CheckDocument = class CheckDocument extends Context.Service()("@effected/git
 	}
 	/** An inert double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({
-		report: overrides.report ?? (() => Effect.sync(() => unstubbed("report"))),
-		checks: overrides.checks ?? Effect.sync(() => unstubbed("checks")),
-		flush: overrides.flush ?? Effect.sync(() => unstubbed("flush"))
+		report: () => dies("report"),
+		checks: dies("checks"),
+		flush: dies("flush"),
+		...overrides
 	});
 	/** {@link CheckDocument.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(CheckDocument, CheckDocument.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`CheckDocument.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("CheckDocument.makeTest");
 
 //#endregion
 export { CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport };