@effected/github-actions 0.12.0 → 0.13.1

package/ActionOutputs.js

@@ -1,5 +1,7 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
 import { WorkflowCommand } from "./WorkflowCommand.js";
+import { heredocBlock, isUsableName } from "./internal/runnerFile.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { Console, Context, Effect, FileSystem, Layer, Schema } from "effect";
 
 //#region src/ActionOutputs.ts
@@ -83,26 +85,65 @@ var DetachedOutputError = class extends Schema.TaggedError()("DetachedOutputErro
 		return `Runner file "${this.file}" cannot be reached from a detached worker — it configures the parent job's later steps, and a worker has none and may outlive the job. Publish this from the parent process instead.`;
 	}
 };
-/** The base delimiter for a heredoc block. */
-const BASE_DELIMITER = "EFFECTED_EOF";
 /**
-* A delimiter guaranteed absent from `value`.
+* The runner file each member appends to — spelled once, so the real layer,
+* the detached layer and the recording double cannot disagree about which
+* file a member's failure names.
+*/
+const RUNNER_FILE = {
+	set: "GITHUB_OUTPUT",
+	setJson: "GITHUB_OUTPUT",
+	exportVariable: "GITHUB_ENV",
+	summary: "GITHUB_STEP_SUMMARY",
+	addPath: "GITHUB_PATH"
+};
+/**
+* Run `effect` only if `name` can head a heredoc block; otherwise fail typed,
+* naming the file. The one name check every construction of the service
+* applies before a named write.
+*/
+const withUsableName = (file, name, effect) => isUsableName(name) ? effect : Effect.fail(new InvalidOutputNameError({
+	file,
+	name
+}));
+/**
+* The JSON text `setJson` publishes for `value`: encoded through `schema`,
+* then stringified. The one step of `setJson` that can fail, shared by the
+* real layer and both test doubles so that none of them can skip it.
+*/
+const encodeJson = (name, value, schema) => Schema.encodeUnknownEffect(Schema.fromJsonString(schema))(value).pipe(Effect.mapError((cause) => new OutputEncodeError({
+	name,
+	cause
+})));
+/**
+* One call an {@link ActionOutputs.recording} double observed.
 *
 * @remarks
-* 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.
+* `value` is always the string the runner would have seen: for `setJson` that
+* is the **encoded** JSON text, after the same schema encode the real layer
+* performs, so a test asserting on it reads exactly what a later step's
+* `steps.<id>.outputs.<name>` expression would. `name` is present for the
+* members that take one (`set`, `setJson`, `exportVariable`) and absent
+* otherwise.
+*
+* @public
 */
-const delimiterFor = (value) => {
-	let delimiter = BASE_DELIMITER;
-	while (value.includes(delimiter)) delimiter = `${delimiter}_`;
-	return delimiter;
-};
-/** A name that would break the block structure it lives in. */
-const isUsableName = (name) => name !== "" && !/[\r\n]/.test(name);
+var RecordedOutput = class extends Schema.Class("RecordedOutput")({
+	/** Which {@link ActionOutputsShape} member was called. */
+	member: Schema.Literals([
+		"set",
+		"setJson",
+		"summary",
+		"exportVariable",
+		"addPath",
+		"setFailed",
+		"setSecret"
+	]),
+	/** The output or variable name, for the members that take one. */
+	name: Schema.optionalKey(Schema.String),
+	/** What was published — value, message, path, content or secret — as the runner would have read it. */
+	value: Schema.String
+}) {};
 const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
 	const fs = yield* FileSystem.FileSystem;
@@ -113,31 +154,19 @@ const make = Effect.gen(function* () {
 			cause
 		})));
 	});
-	const appendBlock = (file, name, value) => {
-		if (!isUsableName(name)) return Effect.fail(new InvalidOutputNameError({
-			file,
-			name
-		}));
-		const delimiter = delimiterFor(value);
-		return append(file, `${name}<<${delimiter}\n${value}\n${delimiter}\n`);
-	};
-	const set = (name, value) => appendBlock("GITHUB_OUTPUT", name, value);
+	const appendBlock = (file, name, value) => withUsableName(file, name, append(file, heredocBlock(name, value)));
+	const set = (name, value) => appendBlock(RUNNER_FILE.set, name, value);
 	return {
 		set,
-		setJson: (name, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new OutputEncodeError({
-			name,
-			cause
-		})), Effect.flatMap((encoded) => set(name, JSON.stringify(encoded)))),
-		summary: (content) => append("GITHUB_STEP_SUMMARY", content),
-		exportVariable: (name, value) => appendBlock("GITHUB_ENV", name, value),
-		addPath: (path) => append("GITHUB_PATH", `${path}\n`),
+		setJson: (name, value, schema) => encodeJson(name, value, schema).pipe(Effect.flatMap((json) => set(name, json))),
+		summary: (content) => append(RUNNER_FILE.summary, content),
+		exportVariable: (name, value) => appendBlock(RUNNER_FILE.exportVariable, name, value),
+		addPath: (path) => append(RUNNER_FILE.addPath, `${path}\n`),
 		setFailed: (message) => Console.log(WorkflowCommand.error(message)),
 		setSecret: (value) => Console.log(WorkflowCommand.addMask(value))
 	};
 });
-const unimplemented = (member) => {
-	throw new Error(`ActionOutputs.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("ActionOutputs.makeTest");
 /**
 * Everything an action publishes: step outputs, exported variables, `PATH`
 * additions, the job summary, log masking and failure annotations.
@@ -195,36 +224,99 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 	*/
 	static layerDetached = Layer.succeed(this, {
 		set: (name) => Effect.fail(new DetachedOutputError({
-			file: "GITHUB_OUTPUT",
+			file: RUNNER_FILE.set,
 			name
 		})),
 		setJson: (name) => Effect.fail(new DetachedOutputError({
-			file: "GITHUB_OUTPUT",
+			file: RUNNER_FILE.setJson,
 			name
 		})),
-		summary: () => Effect.fail(new DetachedOutputError({ file: "GITHUB_STEP_SUMMARY" })),
+		summary: () => Effect.fail(new DetachedOutputError({ file: RUNNER_FILE.summary })),
 		exportVariable: (name) => Effect.fail(new DetachedOutputError({
-			file: "GITHUB_ENV",
+			file: RUNNER_FILE.exportVariable,
 			name
 		})),
-		addPath: () => Effect.fail(new DetachedOutputError({ file: "GITHUB_PATH" })),
+		addPath: () => Effect.fail(new DetachedOutputError({ file: RUNNER_FILE.addPath })),
 		setFailed: (message) => Console.error(message),
 		setSecret: () => Effect.void
 	});
-	/** A test double. Unstubbed members die rather than silently succeeding. */
-	static makeTest = (overrides = {}) => ({
-		set: () => Effect.sync(() => unimplemented("set")),
-		setJson: () => Effect.sync(() => unimplemented("setJson")),
-		summary: () => Effect.sync(() => unimplemented("summary")),
-		exportVariable: () => Effect.sync(() => unimplemented("exportVariable")),
-		addPath: () => Effect.sync(() => unimplemented("addPath")),
-		setFailed: () => Effect.sync(() => unimplemented("setFailed")),
-		setSecret: () => Effect.sync(() => unimplemented("setSecret")),
-		...overrides
-	});
+	/**
+	* A test double. Unstubbed members die rather than silently succeeding.
+	*
+	* @remarks
+	* **`setJson` always encodes first.** The value is encoded through its
+	* schema exactly as the real layer does — failing typed with
+	* {@link OutputEncodeError} — and only then is a supplied `setJson`
+	* override called, with the original `(name, value, schema)`. An override
+	* that accepts `schema` and ignores it therefore **cannot disable
+	* output-schema checking**: a value/schema drift is a typed failure under
+	* this double whether or not the override looks at the schema. Without an
+	* override, a valid value still dies unimplemented as every other unstubbed
+	* member does. Most tests want neither: reach for
+	* {@link ActionOutputs.recording} instead.
+	*/
+	static makeTest = (overrides = {}) => {
+		const setJson = overrides.setJson ?? (() => dies("setJson"));
+		return {
+			set: () => dies("set"),
+			summary: () => dies("summary"),
+			exportVariable: () => dies("exportVariable"),
+			addPath: () => dies("addPath"),
+			setFailed: () => dies("setFailed"),
+			setSecret: () => dies("setSecret"),
+			...overrides,
+			setJson: (name, value, schema) => encodeJson(name, value, schema).pipe(Effect.flatMap(() => setJson(name, value, schema)))
+		};
+	};
 	/** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
 	static layerTest = (overrides = {}) => Layer.succeed(ActionOutputs, ActionOutputs.makeTest(overrides));
+	/**
+	* A recording double: every member appends a {@link RecordedOutput} to a
+	* journal the test reads back, in call order.
+	*
+	* @remarks
+	* This is the double most tests of an action want — "what did it publish?"
+	* — shipped so that nobody hand-writes a `setJson` override that drops the
+	* schema encode (the trap `makeTest` now closes too). `setJson` encodes
+	* through its schema exactly as the real layer does, failing typed with
+	* {@link OutputEncodeError} and recording nothing on a drift, and records
+	* the **encoded JSON text** — what the runner would have read — not the
+	* decoded value. `set`, `exportVariable` and `setJson` refuse an unusable
+	* name with {@link InvalidOutputNameError}, as the real layer does, rather
+	* than recording it.
+	*
+	* `setSecret` records the secret's **plaintext** under
+	* `member: "setSecret"`. That is deliberate for a recording double: the
+	* journal never leaves the test, and a test asserting that a value *was*
+	* masked needs to see which one. Do not hand this journal to anything that
+	* logs.
+	*
+	* Each call returns a fresh, independent journal — there is no state shared
+	* between two `recording()` calls.
+	*/
+	static recording = () => {
+		const entries = [];
+		const record = (member, value, name) => Effect.sync(() => {
+			entries.push(RecordedOutput.make({
+				member,
+				value,
+				...name === void 0 ? {} : { name }
+			}));
+		});
+		return {
+			layer: Layer.succeed(ActionOutputs, {
+				set: (name, value) => withUsableName(RUNNER_FILE.set, name, record("set", value, name)),
+				setJson: (name, value, schema) => withUsableName(RUNNER_FILE.setJson, name, encodeJson(name, value, schema).pipe(Effect.flatMap((json) => record("setJson", json, name)))),
+				summary: (content) => record("summary", content),
+				exportVariable: (name, value) => withUsableName(RUNNER_FILE.exportVariable, name, record("exportVariable", value, name)),
+				addPath: (path) => record("addPath", path),
+				setFailed: (message) => record("setFailed", message),
+				setSecret: (value) => record("setSecret", value)
+			}),
+			entries: () => entries.slice()
+		};
+	};
 };
 
 //#endregion
-export { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RunnerFileUnavailableError, RunnerFileWriteError };
+export { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RecordedOutput, RunnerFileUnavailableError, RunnerFileWriteError };

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)
 	};