@effected/github-actions 0.9.2 → 0.10.1

package/ActionInput.js

@@ -264,10 +264,22 @@ var ActionInput = class ActionInput {
 	* @remarks
 	* Only the **first** `=` splits, so a value may contain one.
 	*
+	* An **empty key** (`=value`, or a bare `=`) is always rejected: `{ "": v }`
+	* cannot be what a workflow meant, and the damage lands far from the typo —
+	* an empty key became a repository filter that matched nothing, and the run
+	* reported zero results with no indication why. An empty **value** (`key=`)
+	* is accepted by default, because setting a property to the empty string is
+	* legitimate; pass `requireValue` to reject it. Every rejection names the
+	* offending line.
+	*
 	* Absent or `""` fails as missing data (see {@link ActionInput.string}) —
 	* `Config.withDefault({})` is the idiom for an optional pairs input.
+	*
+	* @param name - The input name, unmangled.
+	* @param options - `requireValue` rejects a pair whose value is empty.
 	*/
-	static pairs(name) {
+	static pairs(name, options) {
+		const requireValue = options?.requireValue ?? false;
 		return Config.string(inputVariable(name)).pipe(Config.mapOrFail((raw) => {
 			const result = {};
 			for (const line of raw.split("\n")) {
@@ -275,7 +287,11 @@ var ActionInput = class ActionInput {
 				if (stripped === "") continue;
 				const split = stripped.indexOf("=");
 				if (split === -1) return Effect.fail(configError(`Input "${name}" has a line that is not \`key=value\`: "${stripped}"`, raw));
-				result[stripped.slice(0, split).trim()] = stripped.slice(split + 1).trim();
+				const key = stripped.slice(0, split).trim();
+				const value = stripped.slice(split + 1).trim();
+				if (key === "") return Effect.fail(configError(`Input "${name}" has a line with an empty key: "${stripped}"`, raw));
+				if (requireValue && value === "") return Effect.fail(configError(`Input "${name}" has a line with an empty value: "${stripped}"`, raw));
+				result[key] = value;
 			}
 			return Effect.succeed(result);
 		}));

package/ActionOutputs.js

@@ -8,38 +8,79 @@ import { Console, Context, Effect, FileSystem, Layer, Schema } from "effect";
 *
 * @public
 */
-var ActionOutputError = class extends Schema.TaggedError()("ActionOutputError", {
-	/**
-	* `unavailable` — the runner file variable is not set, which usually means
-	* the code is running outside a GitHub runner. `writeFailed` — the file
-	* exists but could not be appended to. `invalidName` — the name would
-	* corrupt the file's block structure. `encodeFailed` — a value did not
-	* satisfy its schema. `detached` — the member was called under
-	* {@link ActionOutputs.layerDetached}, where the channel it writes cannot
-	* reach the job that would read it.
-	*/
-	reason: Schema.Literals([
-		"unavailable",
-		"writeFailed",
-		"invalidName",
-		"encodeFailed",
-		"detached"
-	]),
-	/** Which runner file was involved, by environment variable name. */
+var RunnerFileUnavailableError = class extends Schema.TaggedError()("RunnerFileUnavailableError", {
+	/** The runner file involved, by environment variable name. */
+	file: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Runner file "${this.file}" is not available; is this running on a GitHub runner?`;
+	}
+};
+/**
+* Raised when a runner file exists but could not be appended to.
+*
+* @public
+*/
+var RunnerFileWriteError = class extends Schema.TaggedError()("RunnerFileWriteError", {
+	/** The runner file involved, by environment variable name. */
+	file: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Failed to write to runner file "${this.file}"`;
+	}
+};
+/**
+* Raised when a name would corrupt the runner file's block structure.
+*
+* @public
+*/
+var InvalidOutputNameError = class extends Schema.TaggedError()("InvalidOutputNameError", {
+	/** The offending name. */
+	name: Schema.String,
+	/** The runner file involved, by environment variable name. */
 	file: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `"${this.name}" is not a usable output name`;
+	}
+};
+/**
+* Raised when a value did not satisfy its schema.
+*
+* @public
+*/
+var OutputEncodeError = class extends Schema.TaggedError()("OutputEncodeError", {
+	/** The output or variable name whose value would not encode. */
+	name: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Failed to encode the value for "${this.name}"`;
+	}
+};
+/**
+* Raised when an output member was called under
+* {@link ActionOutputs.layerDetached}.
+*
+* @public
+*/
+var DetachedOutputError = class extends Schema.TaggedError()("DetachedOutputError", {
+	/** The runner file involved, by environment variable name. */
+	file: Schema.String,
 	/** The output or variable name, when one is involved. */
 	name: Schema.optionalKey(Schema.String),
 	/** The underlying failure, preserved structurally. */
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
-		switch (this.reason) {
-			case "unavailable": return `Runner file "${this.file}" is not available; is this running on a GitHub runner?`;
-			case "writeFailed": return `Failed to write to runner file "${this.file}"`;
-			case "invalidName": return `"${this.name}" is not a usable output name`;
-			case "detached": 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.`;
-			default: return `Failed to encode the value for "${this.name}"`;
-		}
+		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. */
@@ -66,19 +107,14 @@ const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
 	const fs = yield* FileSystem.FileSystem;
 	const append = (file, content) => Effect.gen(function* () {
-		const path = yield* env.get(file).pipe(Effect.mapError(() => new ActionOutputError({
-			reason: "unavailable",
-			file
-		})));
-		yield* fs.writeFileString(path, content, { flag: "a" }).pipe(Effect.mapError((cause) => new ActionOutputError({
-			reason: "writeFailed",
+		const path = yield* env.get(file).pipe(Effect.mapError(() => new RunnerFileUnavailableError({ file })));
+		yield* fs.writeFileString(path, content, { flag: "a" }).pipe(Effect.mapError((cause) => new RunnerFileWriteError({
 			file,
 			cause
 		})));
 	});
 	const appendBlock = (file, name, value) => {
-		if (!isUsableName(name)) return Effect.fail(new ActionOutputError({
-			reason: "invalidName",
+		if (!isUsableName(name)) return Effect.fail(new InvalidOutputNameError({
 			file,
 			name
 		}));
@@ -88,8 +124,7 @@ const make = Effect.gen(function* () {
 	const set = (name, value) => appendBlock("GITHUB_OUTPUT", name, value);
 	return {
 		set,
-		setJson: (name, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new ActionOutputError({
-			reason: "encodeFailed",
+		setJson: (name, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new OutputEncodeError({
 			name,
 			cause
 		})), Effect.flatMap((encoded) => set(name, JSON.stringify(encoded)))),
@@ -159,29 +194,20 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 	*   channel to fail through.
 	*/
 	static layerDetached = Layer.succeed(this, {
-		set: (name) => Effect.fail(new ActionOutputError({
-			reason: "detached",
+		set: (name) => Effect.fail(new DetachedOutputError({
 			file: "GITHUB_OUTPUT",
 			name
 		})),
-		setJson: (name) => Effect.fail(new ActionOutputError({
-			reason: "detached",
+		setJson: (name) => Effect.fail(new DetachedOutputError({
 			file: "GITHUB_OUTPUT",
 			name
 		})),
-		summary: () => Effect.fail(new ActionOutputError({
-			reason: "detached",
-			file: "GITHUB_STEP_SUMMARY"
-		})),
-		exportVariable: (name) => Effect.fail(new ActionOutputError({
-			reason: "detached",
+		summary: () => Effect.fail(new DetachedOutputError({ file: "GITHUB_STEP_SUMMARY" })),
+		exportVariable: (name) => Effect.fail(new DetachedOutputError({
 			file: "GITHUB_ENV",
 			name
 		})),
-		addPath: () => Effect.fail(new ActionOutputError({
-			reason: "detached",
-			file: "GITHUB_PATH"
-		})),
+		addPath: () => Effect.fail(new DetachedOutputError({ file: "GITHUB_PATH" })),
 		setFailed: (message) => Console.error(message),
 		setSecret: () => Effect.void
 	});
@@ -201,4 +227,4 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 };
 
 //#endregion
-export { ActionOutputError, ActionOutputs };
+export { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RunnerFileUnavailableError, RunnerFileWriteError };

package/BlobEnvelope.js

@@ -6,35 +6,62 @@ import { Result, Schema } from "effect";
 *
 * @public
 */
-var BlobEnvelopeError = class extends Schema.TaggedError()("BlobEnvelopeError", {
-	/**
-	* `notAnEnvelope` — the magic prefix is absent, so these are raw bytes
-	* written before this format existed (or by something else entirely).
-	* `unsupportedVersion` — an envelope from a newer revision.
-	* `truncated` — the frame ends mid-header or mid-metadata.
-	* `metadataDecodeFailed` — the metadata is well-framed but does not satisfy
-	* the caller's schema. `metadataEncodeFailed` — the value being stored does
-	* not satisfy it.
-	*/
-	reason: Schema.Literals([
-		"notAnEnvelope",
-		"unsupportedVersion",
-		"truncated",
-		"metadataDecodeFailed",
-		"metadataEncodeFailed"
-	]),
-	/** The envelope version found, when one was readable. */
-	version: Schema.optionalKey(Schema.Number),
+var NotABlobEnvelopeError = class extends Schema.TaggedError()("NotABlobEnvelopeError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.optionalKey(Schema.Defect()) }) {
+	get message() {
+		return "Bytes are not an @effected/github-actions blob envelope";
+	}
+};
+/**
+* Raised when the frame ends mid-header or mid-metadata.
+*
+* @public
+*/
+var TruncatedBlobEnvelopeError = class extends Schema.TaggedError()("TruncatedBlobEnvelopeError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.optionalKey(Schema.Defect()) }) {
+	get message() {
+		return "Blob envelope is truncated";
+	}
+};
+/**
+* Raised when the envelope came from a newer revision of the format.
+*
+* @public
+*/
+var UnsupportedBlobEnvelopeVersionError = class extends Schema.TaggedError()("UnsupportedBlobEnvelopeVersionError", {
+	/** The envelope version found. */
+	version: Schema.Number,
+	/** The underlying failure, preserved structurally. */
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
-		switch (this.reason) {
-			case "notAnEnvelope": return "Bytes are not an @effected/github-actions blob envelope";
-			case "unsupportedVersion": return `Blob envelope version ${this.version} is not supported`;
-			case "truncated": return "Blob envelope is truncated";
-			case "metadataDecodeFailed": return "Blob envelope metadata did not satisfy the schema";
-			default: return "Blob metadata could not be encoded";
-		}
+		return `Blob envelope version ${this.version} is not supported`;
+	}
+};
+/**
+* Raised when well-framed metadata does not satisfy the caller's schema.
+*
+* @public
+*/
+var BlobMetadataDecodeError = class extends Schema.TaggedError()("BlobMetadataDecodeError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.optionalKey(Schema.Defect()) }) {
+	get message() {
+		return "Blob envelope metadata did not satisfy the schema";
+	}
+};
+/**
+* Raised when the value being stored does not satisfy its schema.
+*
+* @public
+*/
+var BlobMetadataEncodeError = class extends Schema.TaggedError()("BlobMetadataEncodeError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.optionalKey(Schema.Defect()) }) {
+	get message() {
+		return "Blob metadata could not be encoded";
 	}
 };
 /** Identifies the frame family. Four bytes: `E F B S`. */
@@ -85,10 +112,7 @@ var BlobEnvelope = class {
 	/** Frame metadata and a body into a single blob. */
 	static encodeResult(metadata, body, schema) {
 		const encoded = Schema.encodeUnknownResult(schema)(metadata);
-		if (Result.isFailure(encoded)) return Result.fail(new BlobEnvelopeError({
-			reason: "metadataEncodeFailed",
-			cause: encoded.failure
-		}));
+		if (Result.isFailure(encoded)) return Result.fail(new BlobMetadataEncodeError({ cause: encoded.failure }));
 		const metaBytes = new TextEncoder().encode(JSON.stringify(encoded.success));
 		const out = new Uint8Array(HEADER_BYTES + metaBytes.length + body.length);
 		out.set(MAGIC, 0);
@@ -100,30 +124,21 @@ var BlobEnvelope = class {
 	}
 	/** Read a framed blob back into its metadata and body. */
 	static decodeResult(bytes, schema) {
-		if (bytes.length < MAGIC.length || !MAGIC.every((byte, index) => bytes[index] === byte)) return Result.fail(new BlobEnvelopeError({ reason: "notAnEnvelope" }));
-		if (bytes.length < HEADER_BYTES) return Result.fail(new BlobEnvelopeError({ reason: "truncated" }));
+		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({}));
 		const version = bytes[MAGIC.length] ?? 0;
-		if (version !== VERSION) return Result.fail(new BlobEnvelopeError({
-			reason: "unsupportedVersion",
-			version
-		}));
+		if (version !== VERSION) return Result.fail(new UnsupportedBlobEnvelopeVersionError({ version }));
 		const metaLength = new DataView(bytes.buffer, bytes.byteOffset).getUint32(MAGIC.length + 1, false);
-		if (bytes.length < HEADER_BYTES + metaLength) return Result.fail(new BlobEnvelopeError({ reason: "truncated" }));
+		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 BlobEnvelopeError({
-				reason: "metadataDecodeFailed",
-				cause
-			}));
+			return Result.fail(new BlobMetadataDecodeError({ cause }));
 		}
 		const decoded = Schema.decodeUnknownResult(schema)(parsed);
-		if (Result.isFailure(decoded)) return Result.fail(new BlobEnvelopeError({
-			reason: "metadataDecodeFailed",
-			cause: decoded.failure
-		}));
+		if (Result.isFailure(decoded)) return Result.fail(new BlobMetadataDecodeError({ cause: decoded.failure }));
 		return Result.succeed({
 			metadata: decoded.success,
 			body: bytes.slice(HEADER_BYTES + metaLength)
@@ -132,4 +147,4 @@ var BlobEnvelope = class {
 };
 
 //#endregion
-export { BlobEnvelope, BlobEnvelopeError };
+export { BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, NotABlobEnvelopeError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError };

package/CacheKey.js

@@ -4,27 +4,34 @@ import { GlobSet } from "@effected/glob";
 
 //#region src/CacheKey.ts
 /**
-* Raised when a cache key cannot be derived from the filesystem.
+* Raised when a file or directory that was going to be hashed could not be
+* read.
 *
 * @public
 */
-var CacheKeyError = class extends Schema.TaggedError()("CacheKeyError", {
-	/**
-	* `readFailed` — a file or directory that was going to be hashed could not be
-	* read. `badPattern` — a glob pattern would not compile. Key *derivation*
-	* itself is pure and total once the bytes are in hand, so these are the only
-	* two things that can go wrong.
-	*/
-	reason: Schema.Literals(["readFailed", "badPattern"]),
+var CacheKeyReadError = class extends Schema.TaggedError()("CacheKeyReadError", {
 	/** The path being read when it went wrong. */
-	path: Schema.optionalKey(Schema.String),
+	path: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Could not read "${this.path}" while deriving a cache key`;
+	}
+};
+/**
+* Raised when a glob pattern would not compile.
+*
+* @public
+*/
+var CacheKeyBadPatternError = class extends Schema.TaggedError()("CacheKeyBadPatternError", {
 	/** The pattern that would not compile. */
-	pattern: Schema.optionalKey(Schema.String),
+	pattern: Schema.String,
 	/** The underlying failure, preserved structurally. */
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
-		return this.reason === "readFailed" ? `Could not read "${this.path}" while deriving a cache key` : `"${this.pattern}" is not a usable glob pattern`;
+		return `"${this.pattern}" is not a usable glob pattern`;
 	}
 };
 /**
@@ -188,6 +195,48 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 			restoreDepths: []
 		});
 	}
+	/**
+	* A copy of this key namespaced by `segment` — the whole key, ladder
+	* included.
+	*
+	* @remarks
+	* The cache-bust case: a run that must match nothing an unbusted run wrote,
+	* and whose own entries must be invisible to unbusted runs. Both halves of
+	* that are one intent, and spelling them separately is what makes the wrong
+	* version undetectable — a restore key is a **prefix match**, so folding the
+	* bust in *after* the retained prefix leaves an ordinary run's rung
+	* prefix-matching busted entries. The cache still appears to work, and
+	* quietly serves poisoned entries into unrelated runs.
+	*
+	* Two decisions make this safe for **any** segment value, with no prefix
+	* reasoning at the call site. The segment goes **first**, so the namespaced
+	* key shares no prefix with an unnamespaced one. And the ladder is
+	* **dropped**, so no rung of this key can reach outside the namespace even
+	* when the segment happens to equal an ordinary leading segment — which a
+	* prepend alone would not survive.
+	*
+	* Dropping the ladder is the safe default, not a prohibition: the segments
+	* are all still there, so a caller who wants one busted run to warm from
+	* another can follow with {@link CacheKey.withRestoreDepths} and get an
+	* in-namespace ladder deliberately.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "pnpm-store", "abc123").withNamespace("bust7");
+	* key.key;          // "bust7-Linux-pnpm-store-abc123"
+	* key.restoreKeys;  // []
+	* ```
+	*
+	* @param segment - The namespace, e.g. a cache-bust token.
+	*/
+	withNamespace(segment) {
+		return CacheKey.make({
+			segments: [segment, ...this.segments],
+			restoreDepths: []
+		});
+	}
 	/** Build a key from its segments. */
 	static of(...segments) {
 		return CacheKey.make({ segments });
@@ -278,8 +327,7 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 		const fs = yield* FileSystem.FileSystem;
 		const ordered = [...new Set(files)].sort();
 		if (ordered.length === 0) return Option.none();
-		const digests = yield* Effect.all(ordered.map((path) => fs.readFile(path).pipe(Effect.mapError((cause) => new CacheKeyError({
-			reason: "readFailed",
+		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 });
@@ -313,13 +361,11 @@ 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 set = yield* GlobSet.compile(options.patterns).pipe(Effect.mapError((cause) => new CacheKeyError({
-			reason: "badPattern",
+		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 CacheKeyError({
-			reason: "readFailed",
+		const entries = yield* fs.readDirectory(options.workspace, { recursive: true }).pipe(Effect.mapError((cause) => new CacheKeyReadError({
 			path: options.workspace,
 			cause
 		})));
@@ -327,8 +373,7 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 		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 CacheKeyError({
-				reason: "readFailed",
+			if ((yield* fs.stat(absolute).pipe(Effect.mapError((cause) => new CacheKeyReadError({
 				path: absolute,
 				cause
 			})))).type === "File") matched.push(absolute);
@@ -368,4 +413,4 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 };
 
 //#endregion
-export { CacheKey, CacheKeyError };
+export { CacheKey, CacheKeyBadPatternError, CacheKeyReadError };

package/DetachedProcess.js

@@ -10,37 +10,72 @@ import { closeSync, openSync } from "node:fs";
 *
 * @public
 */
-var DetachedProcessError = class extends Schema.TaggedError()("DetachedProcessError", {
-	/**
-	* `logUnavailable` — the log file could not be opened, so there is nowhere
-	* for the child's output to go. `spawnFailed` — the child did not start.
-	* `invalidPid` — a non-positive pid was handed to {@link DetachedProcess.reap};
-	* see there for why this is the most important value in the module.
-	* `signalFailed` — the signal was refused, e.g. the process belongs to
-	* another user. `notReady` — the readiness probe never held.
-	*/
-	reason: Schema.Literals([
-		"logUnavailable",
-		"spawnFailed",
-		"invalidPid",
-		"signalFailed",
-		"notReady"
-	]),
-	/** The pid involved, when one is. */
-	pid: Schema.optionalKey(Schema.Number),
-	/** The path involved, when one is. */
-	path: Schema.optionalKey(Schema.String),
+var DetachedLogUnavailableError = class extends Schema.TaggedError()("DetachedLogUnavailableError", {
+	/** The log file that could not be opened. */
+	path: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Could not open the detached log file "${this.path}"`;
+	}
+};
+/**
+* Raised when the detached child did not start.
+*
+* @public
+*/
+var DetachedSpawnFailedError = class extends Schema.TaggedError()("DetachedSpawnFailedError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.optionalKey(Schema.Defect()) }) {
+	get message() {
+		return "The detached child did not start";
+	}
+};
+/**
+* Raised when a non-positive pid was handed to {@link DetachedProcess.reap}.
+*
+* @remarks
+* See {@link DetachedProcess.reap} for why this is the most important value in
+* the module: a non-positive pid targets a process *group*, not a process.
+*
+* @public
+*/
+var InvalidPidError = class extends Schema.TaggedError()("InvalidPidError", {
+	/** The pid that was refused. */
+	pid: Schema.Number,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Refusing to signal pid ${this.pid}: a non-positive pid targets a process group, not a process`;
+	}
+};
+/**
+* Raised when a signal was refused, e.g. the process belongs to another user.
+*
+* @public
+*/
+var DetachedSignalFailedError = class extends Schema.TaggedError()("DetachedSignalFailedError", {
+	/** The pid that could not be signalled. */
+	pid: Schema.Number,
 	/** The underlying failure, preserved structurally. */
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
-		switch (this.reason) {
-			case "logUnavailable": return `Could not open the detached log file "${this.path}"`;
-			case "spawnFailed": return "The detached child did not start";
-			case "invalidPid": return `Refusing to signal pid ${this.pid}: a non-positive pid targets a process group, not a process`;
-			case "signalFailed": return `Could not signal pid ${this.pid}`;
-			default: return "The detached child never became ready";
-		}
+		return `Could not signal pid ${this.pid}`;
+	}
+};
+/**
+* Raised when the readiness probe never held.
+*
+* @public
+*/
+var DetachedNotReadyError = class extends Schema.TaggedError()("DetachedNotReadyError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.optionalKey(Schema.Defect()) }) {
+	get message() {
+		return "The detached child never became ready";
 	}
 };
 /**
@@ -129,8 +164,7 @@ var DetachedProcess = class DetachedProcess {
 	static spawn = Effect.fn("DetachedProcess.spawn")(function* (options) {
 		const descriptor = yield* Effect.try({
 			try: () => openSync(options.logFile, "a"),
-			catch: (cause) => new DetachedProcessError({
-				reason: "logUnavailable",
+			catch: (cause) => new DetachedLogUnavailableError({
 				path: options.logFile,
 				cause
 			})
@@ -159,10 +193,7 @@ var DetachedProcess = class DetachedProcess {
 					closeSync(descriptor);
 				}
 			},
-			catch: (cause) => new DetachedProcessError({
-				reason: "spawnFailed",
-				cause
-			})
+			catch: (cause) => new DetachedSpawnFailedError({ cause })
 		});
 		yield* Effect.annotateCurrentSpan({ pid });
 		return ChildProcessSpawner.ProcessId(pid);
@@ -186,7 +217,7 @@ var DetachedProcess = class DetachedProcess {
 		const attempts = options?.attempts ?? 40;
 		const poll = (remaining) => Effect.flatMap(probe, (ready) => {
 			if (ready) return Effect.void;
-			if (remaining <= 0) return Effect.fail(new DetachedProcessError({ reason: "notReady" }));
+			if (remaining <= 0) return Effect.fail(new DetachedNotReadyError({}));
 			return Effect.flatMap(Effect.sleep(interval), () => poll(remaining - 1));
 		});
 		return yield* poll(attempts);
@@ -241,17 +272,13 @@ var DetachedProcess = class DetachedProcess {
 	*/
 	static reap = Effect.fn("DetachedProcess.reap")(function* (pid, signal = "SIGTERM") {
 		yield* Effect.annotateCurrentSpan({ pid });
-		if (!Number.isInteger(pid) || pid <= 0) return yield* Effect.fail(new DetachedProcessError({
-			reason: "invalidPid",
-			pid
-		}));
+		if (!Number.isInteger(pid) || pid <= 0) return yield* Effect.fail(new InvalidPidError({ pid }));
 		return yield* Effect.suspend(() => {
 			try {
 				process.kill(pid, signal);
 				return Effect.succeed(true);
 			} catch (cause) {
-				return isErrno(cause, "ESRCH") ? Effect.succeed(false) : Effect.fail(new DetachedProcessError({
-					reason: "signalFailed",
+				return isErrno(cause, "ESRCH") ? Effect.succeed(false) : Effect.fail(new DetachedSignalFailedError({
 					pid,
 					cause
 				}));
@@ -291,4 +318,4 @@ var DetachedProcess = class DetachedProcess {
 };
 
 //#endregion
-export { DetachedProcess, DetachedProcessError, ProcessId };
+export { DetachedLogUnavailableError, DetachedNotReadyError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, InvalidPidError, ProcessId };

package/PackageManagerInstaller.js

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