@effected/github-actions 0.2.0 → 0.3.0

package/ActionCache.js

@@ -2,10 +2,11 @@ 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 { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema, Stream } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { createHash } from "node:crypto";
 import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
+import { GlobPattern, GlobSet } from "@effected/glob";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 //#region src/ActionCache.ts
@@ -63,6 +64,15 @@ const SERVICE = "github.actions.results.api.v1.CacheService";
 * because upstream does not sort them: sorting here would compute a version no
 * other cache step in the workflow agrees with, and the entry a sibling step
 * wrote would simply never be found.
+*
+* **The digest covers the LITERAL pattern list, never the resolved paths.**
+* That is upstream's choice, not ours: `getCacheVersion` hashes the caller's
+* `paths` argument verbatim (`actions/toolkit`, `cache/src/internal/`
+* `cacheUtils.ts:136-159`), and both `saveCacheV2` (`cache/src/cache.ts:689`)
+* and `restoreCacheV2` (`cache.ts:361`) hand it the un-resolved list — restore
+* never resolves at all. Hashing the resolved list here would compute a
+* version the restore side cannot reproduce, and every save would be an entry
+* no restore ever finds.
 */
 const versionOf = (paths) => createHash("sha256").update([
 	...paths,
@@ -82,9 +92,9 @@ const versionOf = (paths) => createHash("sha256").update([
 const azure = {
 	uploadFile: (url, file) => Effect.tryPromise({
 		try: () => new BlockBlobClient(url).uploadFile(file, {
-			blockSize: 64 * 1024 * 1024,
+			blockSize: 67108864,
 			concurrency: 8,
-			maxSingleShotSize: 128 * 1024 * 1024
+			maxSingleShotSize: 134217728
 		}),
 		catch: (cause) => new BlobTransferError({
 			reason: "uploadFailed",
@@ -144,38 +154,47 @@ const make = (transfer) => Effect.gen(function* () {
 		}).pipe(Effect.mapError((failure) => fromTwirp(failure, key)));
 	});
 	/**
-	* Run `tar`, keeping its stderr.
+	* Run `tar` ONCE, keeping its stderr.
 	*
 	* @remarks
 	* On Windows, extraction runs with `-k` so a file another process holds
 	* open is skipped rather than failing the whole restore — and `tar` then
 	* exits 1 to say so, which is a warning rather than an error. Exit 2 and
 	* above stays a failure on every platform.
+	*
+	* Output and exit code come from the SAME `spawn` handle: the spawner's
+	* `string` and `exitCode` convenience members each spawn independently
+	* (core derives both from `spawn`), so calling them back-to-back
+	* double-executed every archive operation — and on a failure reported the
+	* FIRST run's output as the second run's complaint. `tar` being idempotent
+	* kept this latent here; the same shape failed loudly in
+	* `ToolInstaller.extractZip` on Windows.
 	*/
-	const tar = (args, key, tolerateWarnings) => Effect.gen(function* () {
+	const tar = (args, key, tolerateWarnings) => Effect.scoped(Effect.gen(function* () {
 		const command = ChildProcess.make("tar", [...args]);
-		const output = yield* spawner.string(command, { includeStderr: true }).pipe(Effect.mapError((cause) => new ActionCacheError({
+		const archiveError = (cause) => new ActionCacheError({
 			reason: "archiveFailed",
 			key,
 			cause
-		})));
-		const code = yield* spawner.exitCode(command).pipe(Effect.mapError((cause) => new ActionCacheError({
-			reason: "archiveFailed",
-			key,
-			cause
-		})));
+		});
+		const handle = yield* spawner.spawn(command).pipe(Effect.mapError(archiveError));
+		const output = yield* Stream.mkString(Stream.decodeText(handle.all)).pipe(Effect.mapError(archiveError));
+		const code = yield* handle.exitCode.pipe(Effect.mapError(archiveError));
 		if (code !== 0 && !(tolerateWarnings && code === 1)) return yield* Effect.fail(new ActionCacheError({
 			reason: "archiveFailed",
 			key,
 			stderr: output.trim()
 		}));
-	});
-	/** A scratch archive path, removed on every exit path. */
+	}));
+	/**
+	* A scratch archive path — plus the scratch directory itself, where the
+	* save side writes its tar manifest — removed on every exit path.
+	*/
 	const withArchive = (key, use) => Effect.acquireUseRelease(fs.makeTempDirectory({ prefix: "effected-cache-" }).pipe(Effect.mapError((cause) => new ActionCacheError({
 		reason: "archiveFailed",
 		key,
 		cause
-	}))), (directory) => use(path.join(directory, "cache.tar.gz")), (directory) => Effect.ignore(fs.remove(directory, {
+	}))), (directory) => use(path.join(directory, "cache.tar.gz"), directory), (directory) => Effect.ignore(fs.remove(directory, {
 		recursive: true,
 		force: true
 	})));
@@ -184,6 +203,90 @@ const make = (transfer) => Effect.gen(function* () {
 		key,
 		cause
 	}));
+	/** Platform separators to the dialect's — applied to paths WE produce, never to the caller's pattern text, where a backslash is minimatch's escape character. */
+	const posix = (value) => value.replaceAll("\\", "/");
+	/**
+	* Resolve the caller's patterns to the concrete files and directories
+	* `tar` will archive, with `actions/cache` parity.
+	*
+	* @remarks
+	* The toolkit resolves through `@actions/glob` with `implicitDescendants`
+	* disabled (`cacheUtils.ts:48-70`): a matched directory is answered as
+	* itself and `tar` recurses into it, a pattern that matches nothing —
+	* including a literal path that is not on disk — contributes nothing
+	* (`internal-globber.ts:90-100` existence-filters every search path), a
+	* leading `~` expands to the home directory with the expansion
+	* glob-escaped (`internal-pattern.ts:226-234`), and blank or `#` members
+	* are skipped (the toolkit joins the list with newlines, where both are
+	* inert). A fully empty resolution is the toolkit's hard
+	* "Path Validation Error" (`cache.ts:662-666`) and a typed failure here.
+	*
+	* Two knowing departures: matches stay ABSOLUTE for the `-P` archive
+	* posture rather than being re-rooted at the workspace (the version
+	* hashes the literal list, so the wire protocol never sees the
+	* difference), and the walk does not follow directory symlinks, where
+	* the toolkit's globber does.
+	*/
+	const resolvePaths = (patterns, key) => Effect.gen(function* () {
+		const failed = (detail, cause) => new ActionCacheError({
+			reason: "archiveFailed",
+			key,
+			detail,
+			...cause === void 0 ? {} : { cause }
+		});
+		const cleaned = patterns.map((pattern) => pattern.trim()).filter((p) => p !== "" && !p.startsWith("#"));
+		const workspace = Option.getOrElse(yield* env.getOptional("GITHUB_WORKSPACE"), () => ".");
+		const base = posix(path.resolve(workspace));
+		const rooted = [];
+		for (const pattern of cleaned) {
+			const excluded = pattern.startsWith("!");
+			let target = excluded ? pattern.slice(1) : pattern;
+			if (target === "~" || target.startsWith("~/")) {
+				let home = yield* env.getOptional("HOME");
+				if (Option.isNone(home)) home = yield* env.getOptional("USERPROFILE");
+				if (Option.isNone(home)) return yield* Effect.fail(failed(`cannot expand "~" in "${pattern}" — neither HOME nor USERPROFILE is set`));
+				target = `${GlobPattern.escape(posix(path.resolve(home.value)))}${target.slice(1)}`;
+			}
+			if (!path.isAbsolute(target)) target = `${GlobPattern.escape(base)}/${target}`;
+			rooted.push(excluded ? `!${target}` : target);
+		}
+		const set = yield* GlobSet.compile(rooted).pipe(Effect.mapError((cause) => failed(`"${cause.pattern}" is not a usable glob pattern`, cause)));
+		const roots = [];
+		const wildcardRoots = [];
+		const addRoot = (root, fromWildcard) => {
+			if (root === "") return;
+			if (!roots.includes(root)) roots.push(root);
+			if (fromWildcard && !wildcardRoots.includes(root)) wildcardRoots.push(root);
+		};
+		for (const literal of set.literals) addRoot(literal, false);
+		for (const wildcard of set.wildcards) {
+			if (wildcard.negated) continue;
+			const prefix = wildcard.enumerationPrefix;
+			addRoot(prefix === "" ? base : prefix === "/" ? "/" : prefix.slice(0, -1), true);
+		}
+		const under = (child, parent) => parent === "/" ? child !== "/" : child.startsWith(`${parent}/`);
+		const searchRoots = roots.filter((root) => !roots.some((other) => other !== root && under(root, other)));
+		const needsWalk = (root) => wildcardRoots.some((w) => w === root || under(w, root));
+		const matched = [];
+		const seen = /* @__PURE__ */ new Set();
+		const admit = (candidate) => {
+			if (!seen.has(candidate) && set.matches(candidate)) {
+				seen.add(candidate);
+				matched.push(candidate);
+			}
+		};
+		for (const root of searchRoots) {
+			const info = yield* fs.stat(root).pipe(Effect.option);
+			if (Option.isNone(info)) continue;
+			admit(root);
+			if (info.value.type === "Directory" && needsWalk(root)) {
+				const entries = yield* fs.readDirectory(root, { recursive: true }).pipe(Effect.mapError((cause) => failed(`could not enumerate "${root}"`, cause)));
+				for (const entry of entries) admit(`${root}/${posix(entry)}`);
+			}
+		}
+		if (matched.length === 0) return yield* Effect.fail(failed(`no file or directory matched the cache paths: ${cleaned.join(", ")}`));
+		return matched;
+	});
 	return {
 		save: Effect.fn("ActionCache.save")(function* (paths, key) {
 			const { primary } = ladder(key, void 0);
@@ -194,11 +297,19 @@ const make = (transfer) => Effect.gen(function* () {
 				key: primary,
 				detail: "no paths were given to cache"
 			}));
-			yield* withArchive(primary, (archive) => Effect.gen(function* () {
+			const resolved = yield* resolvePaths(paths, primary);
+			yield* withArchive(primary, (archive, scratch) => Effect.gen(function* () {
+				const manifest = path.join(scratch, "manifest.txt");
+				yield* fs.writeFileString(manifest, `${resolved.join("\n")}\n`).pipe(Effect.mapError((cause) => new ActionCacheError({
+					reason: "archiveFailed",
+					key: primary,
+					cause
+				})));
 				yield* tar([
 					"czPf",
 					archive,
-					...paths
+					"-T",
+					manifest
 				], primary, false);
 				const size = yield* fs.stat(archive).pipe(Effect.mapError((cause) => new ActionCacheError({
 					reason: "archiveFailed",

package/ActionInput.js

@@ -91,6 +91,21 @@ const stripComment = (line) => {
 var ActionInput = class ActionInput {
 	constructor() {}
 	/**
+	* The exact environment variable the runner publishes an input under.
+	*
+	* @remarks
+	* `variable("biome-version")` is `"INPUT_BIOME-VERSION"` — GitHub
+	* uppercases, replaces **spaces** with underscores, and leaves every other
+	* character (**dashes included**) alone. This is the same derivation every
+	* accessor on this class resolves through, exported so a test that must
+	* spell a runner variable can derive it instead of hand-writing it: a
+	* hand-written `INPUT_BIOME_VERSION` reads as absent on a real runner, the
+	* default silently applies, and the suite goes green against the wrong
+	* value. Prefer keying the test environment by input name (see
+	* {@link ActionInput.provider}) so no variable is spelled at all.
+	*/
+	static variable = (name) => inputVariable(name);
+	/**
 	* A required string input.
 	*
 	* @remarks
@@ -250,22 +265,60 @@ var ActionInput = class ActionInput {
 		}));
 	}
 	/**
-	* A `ConfigProvider` over a record of runner variables.
+	* A `ConfigProvider` over a record of runner variables **or input names**.
 	*
 	* @remarks
-	* Subsumes the source package's free-standing `ActionsConfigProvider`, whose
-	* three behaviors are preserved exactly: the path is joined with `_`, spaces
-	* become underscores and the whole is uppercased; and an **empty string
-	* reads as absent**, because the runner sets unsupplied inputs to `""` and
-	* treating that as present would make every optional input look supplied.
+	* The record dual-accepts, and the split is the `INPUT_` prefix:
+	*
+	* - A key already spelled as a runner variable (`INPUT_BIOME-VERSION`,
+	*   `PLAIN_VAR`) is read verbatim, exactly as before.
+	* - Any other key is treated as an **input name**, `with:`-block style —
+	*   `{ "biome-version": "2.3.14" }` — and serves the variable this module
+	*   derives for it (`ActionInput.variable`). This is the spelling to
+	*   prefer in tests: a hand-written `INPUT_BIOME_VERSION` (underscore where
+	*   the runner keeps the dash) reads as absent and the default silently
+	*   applies, and the input-name form makes that class of bug
+	*   unrepresentable — the mangling never leaves this module.
+	*
+	* When both spellings of the same input are present and non-empty, the
+	* explicit `INPUT_`-spelled entry wins.
+	*
+	* A **flat single-segment** lookup additionally tries the `INPUT_`
+	* derivation of the name first, mirroring the order the production runtime
+	* installs ({@link ActionInput.providerOver} via `layerDefault`) — so a
+	* bare `Config.string("biome-version")` resolves under this provider
+	* exactly as it does inside `Action.run`. Nested and numeric paths pass
+	* through as the joined spelling only, as ever.
+	*
+	* The source package's `ActionsConfigProvider` behaviors are otherwise
+	* preserved exactly: the path is joined with `_`, spaces become underscores
+	* and the whole is uppercased; and an **empty string reads as absent**,
+	* because the runner sets unsupplied inputs to `""` and treating that as
+	* present would make every optional input look supplied. That rule applies
+	* to input-name entries too: `{ "flag": "" }` is an unsupplied input.
 	*
 	* Taking the environment as an argument rather than reading `process.env`
 	* is what makes inputs testable without mutating the test process.
 	*/
 	static provider(env = process.env) {
+		/** Unset, and the `""` the runner writes for an unsupplied input, are both absent. */
+		const present = (value) => value !== void 0 && value !== "";
+		/**
+		* Resolve one runner-variable name: the verbatim entry wins; an
+		* `INPUT_`-prefixed miss then consults the input-name entries through the
+		* one spelling of the derivation (`inputVariable`).
+		*/
+		const lookup = (name) => {
+			const direct = env[name];
+			if (present(direct)) return direct;
+			if (name.startsWith("INPUT_")) {
+				for (const [key, value] of Object.entries(env)) if (!key.startsWith("INPUT_") && inputVariable(key) === name && present(value)) return value;
+			}
+		};
 		return ConfigProvider.make((path) => {
-			const value = env[path.join("_").replaceAll(" ", "_").toUpperCase()];
-			return Effect.succeed(value === void 0 || value === "" ? void 0 : ConfigProvider.makeValue(value));
+			const single = path.length === 1 && typeof path[0] === "string" ? path[0] : void 0;
+			const value = (single === void 0 ? void 0 : lookup(inputVariable(single))) ?? lookup(path.join("_").replaceAll(" ", "_").toUpperCase());
+			return Effect.succeed(value === void 0 ? void 0 : ConfigProvider.makeValue(value));
 		});
 	}
 	/**

package/ActionOutputs.js

@@ -14,13 +14,16 @@ var ActionOutputError = class extends Schema.TaggedErrorClass()("ActionOutputErr
 	* 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.
+	* 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"
+		"encodeFailed",
+		"detached"
 	]),
 	/** Which runner file was involved, by environment variable name. */
 	file: Schema.optionalKey(Schema.String),
@@ -34,6 +37,7 @@ var ActionOutputError = class extends Schema.TaggedErrorClass()("ActionOutputErr
 			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}"`;
 		}
 	}
@@ -116,6 +120,71 @@ const unimplemented = (member) => {
 */
 var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/github-actions/ActionOutputs") {
 	static layer = Layer.effect(this, make);
+	/**
+	* The outputs surface that is correct inside a **detached worker**.
+	*
+	* @remarks
+	* The masking model assumes the runner parses stdout. A detached worker's
+	* stdout is a **log file no runner parses**, so under the real layer
+	* `setSecret` emits `::add-mask::<plaintext>` into that file — a command
+	* that is simultaneously **inert** (nothing reads it, so nothing is masked)
+	* and a **secret leak** (the plaintext is now sitting verbatim in a log). A
+	* production action shipped exactly that for one round: an S3 secret and
+	* session token written into a worker's log by the masking call itself.
+	* This layer is the worker-side fix; the parent-side rule is that every
+	* secret a worker will hold is masked **before** the spawn, by
+	* `Secret.forChildEnv` under the real layer.
+	*
+	* The layer needs no environment and no filesystem — its `R` is `never` —
+	* so a worker composing it structurally *cannot* write a runner file.
+	* Per-member behavior:
+	*
+	* - **`setSecret` — silent no-op.** The value must not be written
+	*   *anywhere*: there is no runner on this channel to hand it to, and any
+	*   spelling of it in the log IS the leak. Masking is the parent's job,
+	*   before the worker exists.
+	* - **`set`, `setJson`, `exportVariable`, `addPath`, `summary` — fail
+	*   typed** (`reason: "detached"`, naming the file). Each writes a runner
+	*   file that configures the parent job's *later steps* — `GITHUB_OUTPUT`,
+	*   `GITHUB_ENV`, `GITHUB_PATH` — or is collected when the step completes
+	*   (`GITHUB_STEP_SUMMARY`). A detached worker has no later steps, may
+	*   outlive the job entirely, and even an inherited file path would be
+	*   read at a moment unrelated to the write — so a worker calling one of
+	*   these is a program error worth surfacing, not a write to degrade
+	*   silently.
+	* - **`setFailed` — degrades to a plain log line** (`Console.error`,
+	*   without the `::error::` syntax nothing here would parse). Unlike the
+	*   file members it is log-like: "record that something failed" still
+	*   means something in a worker's log, and its signature carries no error
+	*   channel to fail through.
+	*/
+	static layerDetached = Layer.succeed(this, {
+		set: (name) => Effect.fail(new ActionOutputError({
+			reason: "detached",
+			file: "GITHUB_OUTPUT",
+			name
+		})),
+		setJson: (name) => Effect.fail(new ActionOutputError({
+			reason: "detached",
+			file: "GITHUB_OUTPUT",
+			name
+		})),
+		summary: () => Effect.fail(new ActionOutputError({
+			reason: "detached",
+			file: "GITHUB_STEP_SUMMARY"
+		})),
+		exportVariable: (name) => Effect.fail(new ActionOutputError({
+			reason: "detached",
+			file: "GITHUB_ENV",
+			name
+		})),
+		addPath: () => Effect.fail(new ActionOutputError({
+			reason: "detached",
+			file: "GITHUB_PATH"
+		})),
+		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")),

package/ActionState.js

@@ -12,12 +12,16 @@ var ActionStateError = class extends Schema.TaggedErrorClass()("ActionStateError
 	/**
 	* `missing` — no value was saved under this key in an earlier phase.
 	* `malformed` — a value is there but is not JSON, or does not satisfy the
-	* schema it was read with. `writeFailed` — the state file could not be
+	* schema it was read with. `notPlainJson` — caught at SAVE time: the
+	* schema's encoded form does not survive `JSON.stringify`/`JSON.parse`, so
+	* persisting it would present one phase later as a `malformed` mystery with
+	* no pointer to the cause. `writeFailed` — the state file could not be
 	* appended to.
 	*/
 	reason: Schema.Literals([
 		"missing",
 		"malformed",
+		"notPlainJson",
 		"writeFailed"
 	]),
 	key: Schema.String,
@@ -27,6 +31,7 @@ var ActionStateError = class extends Schema.TaggedErrorClass()("ActionStateError
 		switch (this.reason) {
 			case "missing": return `No action state was saved under "${this.key}"`;
 			case "malformed": return `Action state under "${this.key}" could not be decoded`;
+			case "notPlainJson": return `The encoded form of action state under "${this.key}" is not plain JSON and would not survive the phase boundary — encode to a plain-JSON form (e.g. Schema.OptionFromNullOr rather than Schema.Option)`;
 			default: return `Failed to persist action state under "${this.key}"`;
 		}
 	}
@@ -69,11 +74,33 @@ const make = Effect.gen(function* () {
 		})));
 		return Option.some(decoded);
 	});
-	const save = (key, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new ActionStateError({
-		reason: "malformed",
-		key,
-		cause
-	})), Effect.flatMap((encoded) => write(key, JSON.stringify(encoded))));
+	const save = (key, value, schema) => Effect.gen(function* () {
+		const encoded = yield* Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new ActionStateError({
+			reason: "malformed",
+			key,
+			cause
+		})));
+		const { parsed, serialized } = yield* Effect.try({
+			try: () => {
+				const serialized = JSON.stringify(encoded);
+				return {
+					parsed: JSON.parse(serialized),
+					serialized
+				};
+			},
+			catch: (cause) => new ActionStateError({
+				reason: "notPlainJson",
+				key,
+				cause
+			})
+		});
+		yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(Effect.mapError((cause) => new ActionStateError({
+			reason: "notPlainJson",
+			key,
+			cause
+		})));
+		yield* write(key, serialized);
+	});
 	return {
 		save,
 		getOptional: read,

package/Artifact.js

@@ -84,9 +84,9 @@ const ARTIFACT_VERSION = 7;
 const azure = {
 	uploadFile: (url, file) => Effect.tryPromise({
 		try: () => new BlockBlobClient(url).uploadFile(file, {
-			blockSize: 64 * 1024 * 1024,
+			blockSize: 67108864,
 			concurrency: 8,
-			maxSingleShotSize: 128 * 1024 * 1024
+			maxSingleShotSize: 134217728
 		}),
 		catch: (cause) => new BlobTransferError({
 			reason: "uploadFailed",

package/BlobStore.githubCache.js

@@ -64,7 +64,8 @@ const fromTwirp = (failure, key) => failure.kind === "status" ? new BlobStoreErr
 });
 const make = (transfer) => Effect.gen(function* () {
 	const http = yield* HttpClient.HttpClient;
-	const backend = resultsBackend(yield* ActionEnvironment).pipe(Effect.mapError((name) => new BlobStoreError({
+	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:\``
 	})));

package/CacheKey.js

@@ -48,6 +48,20 @@ const MAX_KEY_LENGTH = 512;
 const Segment = Schema.String.check(Schema.isPattern(/^[^,\n\r]+$/));
 const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values) => values.join(SEPARATOR).length <= MAX_KEY_LENGTH, { title: `a cache key of at most ${MAX_KEY_LENGTH} characters` }));
 /**
+* One explicit rung: how many leading segments it keeps. The upper bound is
+* cross-field (`segments.length - 1`) and lives on the class schema.
+*/
+const RestoreDepth = Schema.Number.check(Schema.isInt(), Schema.isBetween({
+	minimum: 1,
+	maximum: Number.MAX_SAFE_INTEGER
+}));
+/**
+* The explicit ladder: possibly empty, because **zero rungs is a policy** —
+* exact-match-only restores, spelled by {@link CacheKey.withoutRestoreKeys}.
+* Only *absence* means the default every-prefix ladder.
+*/
+const RestoreDepths = Schema.Array(RestoreDepth);
+/**
 * A GitHub Actions cache key and the restore-key ladder that goes with it.
 *
 * @remarks
@@ -58,6 +72,12 @@ const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values)
 * the primary key and its fallbacks impossible to drift apart, which is the
 * failure that produces a cache that never hits and never says why.
 *
+* By default every prefix is a rung. When some segments must never be dropped
+* — a rung without a version digest resurrects stale cross-version caches —
+* give the key an explicit ladder policy with
+* {@link CacheKey.withRestoreDepths}, or none at all with
+* {@link CacheKey.withoutRestoreKeys}, instead of bypassing the typed key.
+*
 * @example
 * ```ts
 * import { CacheKey } from "@effected/github-actions";
@@ -69,9 +89,18 @@ const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values)
 *
 * @public
 */
-var CacheKey = class CacheKey extends Schema.Class("CacheKey")({ 
-/** The components, most general first. */
-segments: Segments }) {
+var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
+	/** The components, most general first. */
+	segments: Segments,
+	/**
+	* The explicit ladder policy, when one was given: how many leading
+	* segments each rung keeps, in the order the rungs are tried. Absent for
+	* the default every-prefix ladder; **empty for no ladder at all** —
+	* exact-match-only. See {@link CacheKey.withRestoreDepths} and
+	* {@link CacheKey.withoutRestoreKeys}.
+	*/
+	restoreDepths: Schema.optionalKey(RestoreDepths)
+}).check(Schema.makeFilter((key) => key.restoreDepths === void 0 || key.restoreDepths.every((depth) => depth <= key.segments.length - 1) ? void 0 : "every restore depth must be between 1 and segments.length - 1 — a rung keeping every segment would just repeat the primary key"))) {
 	/** The primary key: every segment, joined. */
 	get key() {
 		return this.segments.join(SEPARATOR);
@@ -80,16 +109,85 @@ segments: Segments }) {
 	* The restore keys, most specific first.
 	*
 	* @remarks
-	* Each rung drops the last segment and keeps the trailing separator, so a
-	* three-segment key falls back to two prefixes and a one-segment key falls
-	* back to nothing — there is no rung that would match every cache in the
-	* repository.
+	* By default each rung drops the last segment and keeps the trailing
+	* separator, so a three-segment key falls back to two prefixes and a
+	* one-segment key falls back to nothing — there is no rung that would match
+	* every cache in the repository.
+	*
+	* **The default ladder is every prefix**, which is wrong for a key whose
+	* later segments must never be dropped alone: a
+	* `platform-arch-versionHash-branchHash-lockfileHash` key derives rungs
+	* without the version digest, and those resurrect stale cross-version
+	* caches. A key built with {@link CacheKey.withRestoreDepths} carries its
+	* own ladder instead, and this getter answers exactly that ladder — so
+	* `ActionCache.restore` picks the policy up through the same typed-key
+	* path, no hand-built restore-key list required. An **empty** policy
+	* ({@link CacheKey.withoutRestoreKeys}) answers no rungs at all: only
+	* *absence* selects the default ladder, so "none" is never mistaken for
+	* "every prefix".
 	*/
 	get restoreKeys() {
+		const rung = (length) => `${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`;
+		if (this.restoreDepths !== void 0) return this.restoreDepths.map(rung);
 		const rungs = [];
-		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(`${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`);
+		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(rung(length));
 		return rungs;
 	}
+	/**
+	* A copy of this key carrying an explicit restore-key ladder policy.
+	*
+	* @remarks
+	* Each depth is the number of **leading segments** the rung keeps, and the
+	* rungs are emitted in exactly the order given — GitHub tries restore keys
+	* in order, so the order IS the policy. Descending depths (most specific
+	* first) are what a fallback ladder almost always wants; that convention is
+	* recommended rather than enforced, because rung ordering is the consumer's
+	* policy where commas, newlines and the length limit are the runner's
+	* protocol. A depth outside `1..segments.length - 1` is refused at
+	* construction: `0` would match every cache in the repository, and
+	* `segments.length` would just repeat the primary key.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "X64", "v1hash", "main", "lockhash").withRestoreDepths([4, 3]);
+	* key.restoreKeys; // ["Linux-X64-v1hash-main-", "Linux-X64-v1hash-"]
+	* ```
+	*/
+	withRestoreDepths(depths) {
+		return CacheKey.make({
+			segments: this.segments,
+			restoreDepths: depths
+		});
+	}
+	/**
+	* A copy of this key that restores from its **exact key only** — no ladder.
+	*
+	* @remarks
+	* The third point in the policy space, and the one the typed key had no
+	* spelling for: absence of a policy means the default every-prefix ladder,
+	* so exact-match-only restores (a cache-bust mode, where a stale partial
+	* hit is worse than a cold start) previously forced the caller back to the
+	* string form. This is the same `restoreDepths` field carrying **zero
+	* rungs** — an honest value, not a sentinel: `ActionCache.restore` sends no
+	* `restore_keys` at all, so the backend answers this key or a miss.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "pnpm-store", "abc123").withoutRestoreKeys();
+	* key.key;          // "Linux-pnpm-store-abc123"
+	* key.restoreKeys;  // []
+	* ```
+	*/
+	withoutRestoreKeys() {
+		return CacheKey.make({
+			segments: this.segments,
+			restoreDepths: []
+		});
+	}
 	/** Build a key from its segments. */
 	static of(...segments) {
 		return CacheKey.make({ segments });