@effected/github-actions 0.4.1 → 0.5.0

package/ActionEnvironment.js

@@ -275,13 +275,46 @@ var ActionEnvironment = class ActionEnvironment extends Context.Service()("@effe
 	* context variables have one obviously-correct shape, and requiring each
 	* suite to restate them produced a byte-identical block duplicated six times
 	* across the consumers. Overrides merge on top.
+	*
+	* The optional second argument serves {@link ActionEnvironmentShape.payload}
+	* **directly**, replacing the `GITHUB_EVENT_PATH` read rather than seeding a
+	* path and a file behind it. That is the only route to a payload through the
+	* standard double: `TEST_DEFAULTS` deliberately omits `GITHUB_EVENT_PATH`, so
+	* an unserved payload fails typed and names the variable — the die-on-
+	* unstubbed posture the rest of this package keeps.
+	*
+	* `undefined` means *not served*, so a suite cannot arrange `undefined` as
+	* the payload itself. A webhook payload is always a JSON object; the case
+	* does not arise, and reserving the sentinel keeps the argument optional.
 	*/
-	static makeTest = (overrides = {}) => make({
+	static makeTest = (overrides = {}, payload) => Effect.map(make({
 		...TEST_DEFAULTS,
 		...overrides
+	}), (shape) => payload === void 0 ? shape : {
+		...shape,
+		payload: Effect.succeed(payload)
 	});
-	/** {@link ActionEnvironment.makeTest} behind a layer, with `FileSystem` stubbed out. */
-	static layerTest = (overrides = {}) => Layer.effect(ActionEnvironment, ActionEnvironment.makeTest(overrides)).pipe(Layer.provide(FileSystem.layerNoop({})));
+	/**
+	* {@link ActionEnvironment.makeTest} behind a layer, with `FileSystem` stubbed
+	* out.
+	*
+	* @remarks
+	* The stub is why the payload has to be served here rather than through the
+	* filesystem: `make` captures the filesystem at construction, so seeding
+	* `GITHUB_EVENT_PATH` through `overrides` would send the read to a noop
+	* filesystem and fail. Pass the payload as the second argument instead.
+	*
+	* @example
+	* ```ts
+	* import { ActionEnvironment } from "@effected/github-actions";
+	*
+	* const layer = ActionEnvironment.layerTest(
+	*   { GITHUB_EVENT_NAME: "pull_request" },
+	*   { pull_request: { number: 42 } },
+	* );
+	* ```
+	*/
+	static layerTest = (overrides = {}, payload) => Layer.effect(ActionEnvironment, ActionEnvironment.makeTest(overrides, payload)).pipe(Layer.provide(FileSystem.layerNoop({})));
 };
 
 //#endregion

package/ActionInput.js

@@ -115,6 +115,43 @@ var ActionInput = class ActionInput {
 	* Every accessor on this class shares the rule, so an **optional** input
 	* needs `Config.withDefault` (or `Config.option`) at the call site or the
 	* read fails outright.
+	*
+	* **An input whose documented meaning is "set it empty to disable this"
+	* cannot be read with `Config.withDefault`.** Empty is classified as missing
+	* *before* the default is consulted, so the default substitutes and the
+	* documented behavior can never happen. A live action shipped exactly that
+	* for its whole lifetime: `action.yml` promised `release-prefix: ""` would
+	* disable retry, and it never could. `Config.option` is the shape that
+	* distinguishes the states:
+	*
+	* ```ts
+	* Config.option(ActionInput.string("release-prefix"))
+	* // WITH a non-empty default in action.yml:
+	* //   unsupplied     -> Some("release:")   (the manifest default, via the runner)
+	* //   explicit ""    -> None
+	* //   explicit value -> Some(value)
+	* // WITHOUT a default in action.yml:
+	* //   unsupplied     -> None               (the runner still writes the variable, empty)
+	* ```
+	*
+	* Both rows matter: "the runner writes `""` for an unsupplied input" is the
+	* no-default case, and it is the manifest default — when there is one — that
+	* makes the unsupplied and explicitly-empty cases distinguishable at all.
+	*
+	* Two consequences follow from how the runner actually behaves, both
+	* confirmed against `actions/runner` and on a live runner:
+	*
+	* - **The runner publishes a variable for every declared input**, so *absent*
+	*   is a state a runner never produces. The `Some` branch above depends on
+	*   `action.yml` declaring a **non-empty default** — a fact in a different
+	*   file, invisible at this call site. Deleting that default does not restore
+	*   a fallback; an input declaring no default arrives set-and-empty when
+	*   unsupplied, silently flipping every unsupplied run to `None`. Pin the
+	*   default with a test if a read depends on it.
+	* - **A bare test environment inverts the unsupplied case.** Omitting the key
+	*   in a test means genuinely absent, which no runner emits, so a test named
+	*   "unsupplied" asserts the opposite of production and passes. Arrange the
+	*   manifest default explicitly instead of omitting the key.
 	*/
 	static string(name) {
 		return Config.string(inputVariable(name));
@@ -299,6 +336,22 @@ var ActionInput = class ActionInput {
 	*
 	* Taking the environment as an argument rather than reading `process.env`
 	* is what makes inputs testable without mutating the test process.
+	*
+	* **A bare `ConfigProvider.fromEnv` cannot serve input-name keys.** Composed
+	* beneath this provider or {@link ActionInput.providerOver}, it uppercases
+	* the config path, so `{ "target-branch": "trunk" }` is looked up as
+	* `TARGET-BRANCH`, never matches, and the read falls through to whatever
+	* default the call site supplies. It **fails green**: nothing errors, the
+	* suite passes against the default, and the test's name claims it proved the
+	* input was read. A consuming action's integration harness did exactly this
+	* and stayed green across several commits while a supplied `target-branch`
+	* silently did nothing.
+	*
+	* Runner-variable keys (`INPUT_TARGET-BRANCH`, `PLAIN_VAR`) are unaffected —
+	* they are already in the spelling `fromEnv` produces, and they resolve. The
+	* hazard is specific to keying a `fromEnv` record by **input name**. Passing
+	* the record to *this* function instead removes the distinction: it
+	* dual-accepts both spellings, so neither can miss.
 	*/
 	static provider(env = process.env) {
 		/** Unset, and the `""` the runner writes for an unsupplied input, are both absent. */
@@ -362,6 +415,22 @@ var ActionInput = class ActionInput {
 	* `ActionInput` accessors themselves are unaffected — they read
 	* `INPUT_<MANGLED>` names, whose re-mangled form (`INPUT_INPUT_…`) never
 	* matches, so they fall through to the ambient lookup they always used.
+	*
+	* **A bare `ConfigProvider.fromEnv({ env })` here serves only runner-variable
+	* keys.** `INPUT_TARGET-BRANCH` and `PLAIN_VAR` resolve; an input-name key
+	* like `target-branch` is uppercased to `TARGET-BRANCH`, never matches, and
+	* fails green — see {@link ActionInput.provider} for the mechanism. Use
+	* `ActionInput.provider(env)`, which dual-accepts both spellings.
+	*
+	* **The single-segment retry above makes the obvious test
+	* non-discriminating**, which is worth knowing before writing one. Because a
+	* bare `Config.string("release-branch")` resolves through the same `INPUT_`
+	* derivation as `ActionInput.string("release-branch")`, a test meant to prove
+	* the accessor reads the mangled key passes just as well with the accessor
+	* swapped for a bare `Config`. Only a bare `fromEnv` underneath tells them
+	* apart — and that is the one shape you should never reach for. Test the
+	* derivation through `ActionInput.variable` instead of trying to catch it by
+	* substitution.
 	*/
 	static providerOver(ambient) {
 		return ConfigProvider.orElse(ConfigProvider.make((path) => {
@@ -380,9 +449,16 @@ var ActionInput = class ActionInput {
 	* `ConfigProvider` layer still wins by normal layer precedence.
 	*
 	* The ambient half is whatever provider is **explicitly installed** when the
-	* layer builds — which is how a test injects a deterministic environment by
-	* providing `ConfigProvider.layer(ConfigProvider.fromEnv({ env }))` beneath
-	* the runtime. When none is installed, a **fresh** `ConfigProvider.fromEnv()`
+	* layer builds — which is how a test injects a deterministic environment, by
+	* providing `ConfigProvider.layer(ActionInput.provider(env))` beneath the
+	* runtime. Prefer `ActionInput.provider` over a bare
+	* `ConfigProvider.fromEnv({ env })`: `fromEnv` serves runner-variable keys
+	* fine, but uppercases the config path, so a record keyed by **input name**
+	* never matches and every such read silently takes its default while the
+	* suite stays green ({@link ActionInput.provider} has the full account).
+	* `ActionInput.provider` dual-accepts both spellings, so neither can miss.
+	*
+	* When none is installed, a **fresh** `ConfigProvider.fromEnv()`
 	* is built rather than reading the reference's default: v4 caches that
 	* default once per process, and a snapshot taken before the runner's
 	* variables are visible would resurrect exactly the missed-input class this

package/ActionLogger.js

@@ -109,25 +109,27 @@ const flush = (state) => Effect.suspend(() => {
 const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
 	const flushActive = Effect.flatMap(ActiveBuffer, (state) => state === null ? Effect.void : flush(state));
+	const withBuffer = (label, effect, options) => Effect.gen(function* () {
+		const minimum = yield* References.MinimumLogLevel;
+		if ((yield* env.isDebug) || LogLevel.isLessThanOrEqualTo(minimum, "Debug")) return yield* effect;
+		const state = {
+			label,
+			entries: []
+		};
+		const buffering = Logger.make((options) => {
+			if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Warn")) {
+				const annotations = options.fiber.getRef(References.CurrentLogAnnotations);
+				options.fiber.getRef(Console.Console).log(renderEntry(options.logLevel, options.message, annotations));
+				return;
+			}
+			state.entries.push(formatMessage(options.message));
+		});
+		return yield* effect.pipe(Effect.provideService(References.MinimumLogLevel, "All"), Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([buffering])), Effect.provideService(ActiveBuffer, state), Effect.onExit((exit) => Exit.isSuccess(exit) && options?.onSuccess === "discard" ? discard(state) : flush(state)));
+	});
 	return {
 		group: (name, effect) => Effect.acquireUseRelease(Console.log(WorkflowCommand.group(name)), () => Effect.tapCause(effect, () => flushActive), () => Console.log(WorkflowCommand.endGroup())),
-		withBuffer: (label, effect, options) => Effect.gen(function* () {
-			const minimum = yield* References.MinimumLogLevel;
-			if ((yield* env.isDebug) || LogLevel.isLessThanOrEqualTo(minimum, "Debug")) return yield* effect;
-			const state = {
-				label,
-				entries: []
-			};
-			const buffering = Logger.make((options) => {
-				if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Warn")) {
-					const annotations = options.fiber.getRef(References.CurrentLogAnnotations);
-					options.fiber.getRef(Console.Console).log(renderEntry(options.logLevel, options.message, annotations));
-					return;
-				}
-				state.entries.push(formatMessage(options.message));
-			});
-			return yield* effect.pipe(Effect.provideService(References.MinimumLogLevel, "All"), Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([buffering])), Effect.provideService(ActiveBuffer, state), Effect.onExit((exit) => Exit.isSuccess(exit) && options?.onSuccess === "discard" ? discard(state) : flush(state)));
-		}),
+		withBuffer,
+		withStep: (name, effect, options) => withBuffer(name, Effect.tapCause(effect, () => Console.log(`❌ ${name}`)), { onSuccess: "discard" }).pipe(Effect.tap(() => Effect.logInfo(options?.summary ?? `✅ ${name}`))),
 		notice: (message, properties = {}) => Console.log(WorkflowCommand.notice(message, properties)),
 		annotated: (properties, effect) => Effect.annotateLogs(effect, annotationRecord(properties))
 	};
@@ -187,6 +189,7 @@ var ActionLogger = class ActionLogger extends Context.Service()("@effected/githu
 	static makeTest = (overrides = {}) => ({
 		group: (_name, effect) => effect,
 		withBuffer: (_label, effect) => effect,
+		withStep: (_name, effect) => effect,
 		notice: () => Effect.void,
 		annotated: (_properties, effect) => effect,
 		...overrides

package/GitHubMarkdown.js

@@ -13,11 +13,25 @@ const passthrough = (value) => Html.make({ value });
 *
 * @remarks
 * `Markdown.stringifyResult` is total over every tree this module can
-* construct — its only failure is the hardening depth cap, which a
-* fixed-shape two-level tree cannot reach — so the impossible arm is a
-* defect, **not** a silent fallback to unescaped string joining. The
-* predecessor's fallback arm is the live table-corruption defect this module
-* exists to delete.
+* construct — its only failure is the hardening nesting-depth guard (cap
+* 256) — so the impossible arm is a defect, **not** a silent fallback to
+* unescaped string joining. The predecessor's fallback arm is the live
+* table-corruption defect this module exists to delete.
+*
+* What makes the guard unreachable is not that these trees are small; it is
+* that **their depth does not depend on input**. A fragment handed to a
+* member always becomes a **leaf**, never a subtree: the composition members
+* (`table`, `list`, `link`) wrap it in a single `passthrough` node, and the
+* content members (`code`, `codeBlock`) carry it as a node's `value` string.
+* Either way nothing re-parses a fragment into child nodes, so a composition
+* nests strings rather than nodes and the deepest tree the writer can build
+* is a table's five levels, whatever it is handed. Pinned by
+* `__test__/GitHubMarkdown.test.ts`, which nests the writer's own output a
+* thousand deep — four times the cap — and still renders.
+*
+* Keep that property when adding a member: a member that accepts a *node*, or
+* that re-parses a fragment into one, makes depth input-dependent and this
+* whole argument — and the no-wrapping guidance on the class — collapses.
 */
 const render = (root) => Result.getOrThrow(Markdown.stringifyResult(root)).trimEnd();
 const block = (node) => render(Root.make({ children: [node] }));
@@ -41,6 +55,22 @@ const block = (node) => render(Root.make({ children: [node] }));
 * structural test pins that, on the same terms as the Azure confinement — so
 * an action that never renders markdown never links the engine.
 *
+* **Renders cannot fail, so do not `Effect.try`-wrap them.** The serializer's
+* single failure mode is a nesting-depth guard, and no input can reach it: a
+* fragment handed to a member becomes a leaf — a passthrough node or a node's
+* `value` string — never a parsed subtree, so a composition nests strings
+* rather than nodes and the tree's depth is fixed by the construct, not by
+* what it is handed. A test nests the writer's own output a thousand deep and
+* still renders. Wrapping is boilerplate that also widens the catch to
+* anything else thrown inside the builder — a reporting surface degrading for
+* reasons it did not intend.
+*
+* Two exceptions, both in {@link GitHubMarkdown.tableFor} and neither in the
+* serializer. Cells encode through the row schema, so a value smuggled past
+* the types throws its `SchemaError`; and a column's own `format` function is
+* called directly, so its totality is the caller's to guarantee. Well-typed
+* rows through the default codec are total.
+*
 * @example
 * ```ts
 * import { GitHubMarkdown } from "@effected/github-actions";
@@ -95,6 +125,19 @@ var GitHubMarkdown = class GitHubMarkdown {
 	* past the types throws the codec's `SchemaError` as a defect — same
 	* posture as the serializer arm above, **not** a silent fallback.
 	*
+	* This is the **only** member where a throw is reachable at runtime, and
+	* neither route is the serializer — see the no-wrapping remark on
+	* {@link GitHubMarkdown}. There are two:
+	*
+	* - the **codec**, for a value smuggled past the types. A caller holding
+	*   only well-typed rows (the normal case, and what the types express)
+	*   needs no wrapping; a caller feeding rows decoded from somewhere
+	*   untyped should decode through the schema rather than guard the render.
+	* - a column's own **`format`** function, which is called directly and
+	*   bypasses the codec entirely. Nothing here can make user code total, so
+	*   a `format` that can throw makes its render able to throw — keep
+	*   formatters total, or guard at the formatter rather than the render.
+	*
 	* Only string-keyed fields become columns; symbol keys are not
 	* enumerable table columns.
 	*

package/README.md

@@ -202,7 +202,16 @@ The debounce is trailing with a max-wait, so a burst of reports coalesces into o
 
 ## Testing
 
-Every service ships `makeTest(overrides?)` and `layerTest(overrides?)`, with unstubbed members dying loudly and naming themselves — three recorded exceptions state why they default instead: `ActionEnvironment.makeTest` seeds the twelve `GITHUB_*`/`RUNNER_*` variables, `ActionLogger.makeTest` defaults to silent, and `DryRun.makeTest` defaults to rehearsing, the safe direction:
+Every service ships `makeTest(overrides?)` and `layerTest(overrides?)`, with unstubbed members dying loudly and naming themselves — three recorded exceptions state why they default instead: `ActionEnvironment.makeTest` seeds the twelve `GITHUB_*`/`RUNNER_*` variables, `ActionLogger.makeTest` defaults to silent, and `DryRun.makeTest` defaults to rehearsing, the safe direction. `ActionEnvironment.makeTest`/`layerTest` also take the webhook event payload as an optional second argument, serving it directly instead of routing it through a `GITHUB_EVENT_PATH` filesystem read the stubbed filesystem could never satisfy:
+
+```ts
+import { ActionEnvironment } from "@effected/github-actions";
+
+const layer = ActionEnvironment.layerTest(
+  { GITHUB_EVENT_NAME: "pull_request" },
+  { pull_request: { number: 42 } },
+);
+```
 
 ```ts
 import { ActionOutputs } from "@effected/github-actions";
@@ -221,7 +230,7 @@ const TestOutputs = ActionOutputs.layerTest({
 - `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default.
 - `ActionOutputs` — step outputs, JSON outputs, the job summary, exported variables, `PATH` additions, failure annotations and log masking.
 - `ActionState` / `ActionEnvironment` — persisted `pre`/`main`/`post` state, and the fiber-local `GITHUB_*`/`RUNNER_*` context read once from `process.env`.
-- `ActionLogger` — collapsible groups, buffered step transcripts (`withBuffer({ onSuccess: "discard" })` keeps a green log to one line per step, while a failure, defect or interruption still flushes), `::notice::` annotations, and the `Logger` that renders every `Effect.log*` as a workflow command.
+- `ActionLogger` — collapsible groups, buffered step transcripts (`withBuffer({ onSuccess: "discard" })` drops a green step's transcript entirely, while a failure, defect or interruption still flushes it), `withStep(name, effect, options?)` for the same buffering plus one summary line on success and a `❌ <name>` header above the transcript on failure, `::notice::` annotations, and the `Logger` that renders every `Effect.log*` as a workflow command.
 - `DryRun` — the rehearsal guard every mutation goes through, driven by the `dry-run` input by default.
 - `Secret` — the one declassification seam between a `Redacted` value and a plain string, masking before it returns plaintext.
 - `GitHubToken` — the App-token lifecycle shaped like the `pre`/`main`/`post` workflow: mint, verify scopes, persist, read, revoke.

package/index.d.ts

@@ -183,10 +183,40 @@ declare class ActionEnvironment extends ActionEnvironment_base {
    * context variables have one obviously-correct shape, and requiring each
    * suite to restate them produced a byte-identical block duplicated six times
    * across the consumers. Overrides merge on top.
+   *
+   * The optional second argument serves {@link ActionEnvironmentShape.payload}
+   * **directly**, replacing the `GITHUB_EVENT_PATH` read rather than seeding a
+   * path and a file behind it. That is the only route to a payload through the
+   * standard double: `TEST_DEFAULTS` deliberately omits `GITHUB_EVENT_PATH`, so
+   * an unserved payload fails typed and names the variable — the die-on-
+   * unstubbed posture the rest of this package keeps.
+   *
+   * `undefined` means *not served*, so a suite cannot arrange `undefined` as
+   * the payload itself. A webhook payload is always a JSON object; the case
+   * does not arise, and reserving the sentinel keeps the argument optional.
    */
-  static readonly makeTest: (overrides?: Readonly<Record<string, string>>) => Effect.Effect<ActionEnvironmentShape, never, FileSystem.FileSystem>;
-  /** {@link ActionEnvironment.makeTest} behind a layer, with `FileSystem` stubbed out. */
-  static readonly layerTest: (overrides?: Readonly<Record<string, string>>) => Layer.Layer<ActionEnvironment>;
+  static readonly makeTest: (overrides?: Readonly<Record<string, string>>, payload?: unknown) => Effect.Effect<ActionEnvironmentShape, never, FileSystem.FileSystem>;
+  /**
+   * {@link ActionEnvironment.makeTest} behind a layer, with `FileSystem` stubbed
+   * out.
+   *
+   * @remarks
+   * The stub is why the payload has to be served here rather than through the
+   * filesystem: `make` captures the filesystem at construction, so seeding
+   * `GITHUB_EVENT_PATH` through `overrides` would send the read to a noop
+   * filesystem and fail. Pass the payload as the second argument instead.
+   *
+   * @example
+   * ```ts
+   * import { ActionEnvironment } from "@effected/github-actions";
+   *
+   * const layer = ActionEnvironment.layerTest(
+   *   { GITHUB_EVENT_NAME: "pull_request" },
+   *   { pull_request: { number: 42 } },
+   * );
+   * ```
+   */
+  static readonly layerTest: (overrides?: Readonly<Record<string, string>>, payload?: unknown) => Layer.Layer<ActionEnvironment>;
 }
 //#endregion
 //#region src/WorkflowCommand.d.ts
@@ -286,6 +316,21 @@ interface WithBufferOptions {
    */
   readonly onSuccess?: "flush" | "discard";
 }
+/**
+ * Options for {@link ActionLoggerShape.withStep}.
+ *
+ * @public
+ */
+interface WithStepOptions {
+  /**
+   * The info line emitted when the step **succeeds**.
+   *
+   * @remarks
+   * Defaults to `✅ <name>`. This is the line the buffered transcript is traded
+   * for: a green step reports that it happened and nothing else.
+   */
+  readonly summary?: string;
+}
 /**
  * The {@link ActionLogger} service shape.
  *
@@ -313,6 +358,40 @@ interface ActionLoggerShape {
    * what a green step did.
    */
   readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>, options?: WithBufferOptions) => Effect.Effect<A, E, R>;
+  /**
+   * Run a named step: quiet when it succeeds, its full transcript when it does
+   * not.
+   *
+   * @remarks
+   * The composition a release log actually wants, and the one
+   * {@link ActionLoggerShape.withBuffer} alone does not reach. Buffering with
+   * `{ onSuccess: "discard" }` gets a green step to *zero* lines; this trades
+   * that transcript for exactly one:
+   *
+   * 1. verbose output is captured rather than printed live,
+   * 2. on success the transcript is dropped and a single info line — `summary`,
+   *    default `✅ <name>` ({@link WithStepOptions}) — goes out in its place,
+   * 3. on failure a `❌ <name>` header lands **first**, then the transcript
+   *    spills beneath it.
+   *
+   * The ordering in (3) is a property of the **buffered** path. With step
+   * debugging on, nothing is buffered — verbose output has already gone out
+   * live by the time the failure fires — so the header lands *after* the
+   * transcript it would otherwise introduce. That is the honest trade of
+   * asking for live output, not a defect, and both orderings are pinned by
+   * test.
+   *
+   * The header and the summary are the whole difference from `withBuffer`, and
+   * they are why this is a member rather than a documented recipe: the recipe
+   * was independently derived wrong three times by careful readers during one
+   * port, because `group` + `withBuffer` looks like complete parity until you
+   * notice nothing emits the success line.
+   *
+   * The summary survives step debugging. Buffering is skipped when the runner
+   * asks for verbose output, but the line naming what succeeded is still the
+   * cheapest thing in the log.
+   */
+  readonly withStep: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>, options?: WithStepOptions) => Effect.Effect<A, E, R>;
   /**
    * Emit a `::notice::` annotation.
    *
@@ -1273,6 +1352,43 @@ declare class ActionInput {
    * Every accessor on this class shares the rule, so an **optional** input
    * needs `Config.withDefault` (or `Config.option`) at the call site or the
    * read fails outright.
+   *
+   * **An input whose documented meaning is "set it empty to disable this"
+   * cannot be read with `Config.withDefault`.** Empty is classified as missing
+   * *before* the default is consulted, so the default substitutes and the
+   * documented behavior can never happen. A live action shipped exactly that
+   * for its whole lifetime: `action.yml` promised `release-prefix: ""` would
+   * disable retry, and it never could. `Config.option` is the shape that
+   * distinguishes the states:
+   *
+   * ```ts
+   * Config.option(ActionInput.string("release-prefix"))
+   * // WITH a non-empty default in action.yml:
+   * //   unsupplied     -> Some("release:")   (the manifest default, via the runner)
+   * //   explicit ""    -> None
+   * //   explicit value -> Some(value)
+   * // WITHOUT a default in action.yml:
+   * //   unsupplied     -> None               (the runner still writes the variable, empty)
+   * ```
+   *
+   * Both rows matter: "the runner writes `""` for an unsupplied input" is the
+   * no-default case, and it is the manifest default — when there is one — that
+   * makes the unsupplied and explicitly-empty cases distinguishable at all.
+   *
+   * Two consequences follow from how the runner actually behaves, both
+   * confirmed against `actions/runner` and on a live runner:
+   *
+   * - **The runner publishes a variable for every declared input**, so *absent*
+   *   is a state a runner never produces. The `Some` branch above depends on
+   *   `action.yml` declaring a **non-empty default** — a fact in a different
+   *   file, invisible at this call site. Deleting that default does not restore
+   *   a fallback; an input declaring no default arrives set-and-empty when
+   *   unsupplied, silently flipping every unsupplied run to `None`. Pin the
+   *   default with a test if a read depends on it.
+   * - **A bare test environment inverts the unsupplied case.** Omitting the key
+   *   in a test means genuinely absent, which no runner emits, so a test named
+   *   "unsupplied" asserts the opposite of production and passes. Arrange the
+   *   manifest default explicitly instead of omitting the key.
    */
   static string(name: string): Config.Config<string>;
   /**
@@ -1406,6 +1522,22 @@ declare class ActionInput {
    *
    * Taking the environment as an argument rather than reading `process.env`
    * is what makes inputs testable without mutating the test process.
+   *
+   * **A bare `ConfigProvider.fromEnv` cannot serve input-name keys.** Composed
+   * beneath this provider or {@link ActionInput.providerOver}, it uppercases
+   * the config path, so `{ "target-branch": "trunk" }` is looked up as
+   * `TARGET-BRANCH`, never matches, and the read falls through to whatever
+   * default the call site supplies. It **fails green**: nothing errors, the
+   * suite passes against the default, and the test's name claims it proved the
+   * input was read. A consuming action's integration harness did exactly this
+   * and stayed green across several commits while a supplied `target-branch`
+   * silently did nothing.
+   *
+   * Runner-variable keys (`INPUT_TARGET-BRANCH`, `PLAIN_VAR`) are unaffected —
+   * they are already in the spelling `fromEnv` produces, and they resolve. The
+   * hazard is specific to keying a `fromEnv` record by **input name**. Passing
+   * the record to *this* function instead removes the distinction: it
+   * dual-accepts both spellings, so neither can miss.
    */
   static provider(env?: Readonly<Record<string, string | undefined>>): ConfigProvider.ConfigProvider;
   /**
@@ -1447,6 +1579,22 @@ declare class ActionInput {
    * `ActionInput` accessors themselves are unaffected — they read
    * `INPUT_<MANGLED>` names, whose re-mangled form (`INPUT_INPUT_…`) never
    * matches, so they fall through to the ambient lookup they always used.
+   *
+   * **A bare `ConfigProvider.fromEnv({ env })` here serves only runner-variable
+   * keys.** `INPUT_TARGET-BRANCH` and `PLAIN_VAR` resolve; an input-name key
+   * like `target-branch` is uppercased to `TARGET-BRANCH`, never matches, and
+   * fails green — see {@link ActionInput.provider} for the mechanism. Use
+   * `ActionInput.provider(env)`, which dual-accepts both spellings.
+   *
+   * **The single-segment retry above makes the obvious test
+   * non-discriminating**, which is worth knowing before writing one. Because a
+   * bare `Config.string("release-branch")` resolves through the same `INPUT_`
+   * derivation as `ActionInput.string("release-branch")`, a test meant to prove
+   * the accessor reads the mangled key passes just as well with the accessor
+   * swapped for a bare `Config`. Only a bare `fromEnv` underneath tells them
+   * apart — and that is the one shape you should never reach for. Test the
+   * derivation through `ActionInput.variable` instead of trying to catch it by
+   * substitution.
    */
   static providerOver(ambient: ConfigProvider.ConfigProvider): ConfigProvider.ConfigProvider;
   /**
@@ -1460,9 +1608,16 @@ declare class ActionInput {
    * `ConfigProvider` layer still wins by normal layer precedence.
    *
    * The ambient half is whatever provider is **explicitly installed** when the
-   * layer builds — which is how a test injects a deterministic environment by
-   * providing `ConfigProvider.layer(ConfigProvider.fromEnv({ env }))` beneath
-   * the runtime. When none is installed, a **fresh** `ConfigProvider.fromEnv()`
+   * layer builds — which is how a test injects a deterministic environment, by
+   * providing `ConfigProvider.layer(ActionInput.provider(env))` beneath the
+   * runtime. Prefer `ActionInput.provider` over a bare
+   * `ConfigProvider.fromEnv({ env })`: `fromEnv` serves runner-variable keys
+   * fine, but uppercases the config path, so a record keyed by **input name**
+   * never matches and every such read silently takes its default while the
+   * suite stays green ({@link ActionInput.provider} has the full account).
+   * `ActionInput.provider` dual-accepts both spellings, so neither can miss.
+   *
+   * When none is installed, a **fresh** `ConfigProvider.fromEnv()`
    * is built rather than reading the reference's default: v4 caches that
    * default once per process, and a snapshot taken before the runner's
    * variables are visible would resurrect exactly the missed-input class this
@@ -3023,6 +3178,22 @@ interface GitHubSchemaTable<Row> {
  * structural test pins that, on the same terms as the Azure confinement — so
  * an action that never renders markdown never links the engine.
  *
+ * **Renders cannot fail, so do not `Effect.try`-wrap them.** The serializer's
+ * single failure mode is a nesting-depth guard, and no input can reach it: a
+ * fragment handed to a member becomes a leaf — a passthrough node or a node's
+ * `value` string — never a parsed subtree, so a composition nests strings
+ * rather than nodes and the tree's depth is fixed by the construct, not by
+ * what it is handed. A test nests the writer's own output a thousand deep and
+ * still renders. Wrapping is boilerplate that also widens the catch to
+ * anything else thrown inside the builder — a reporting surface degrading for
+ * reasons it did not intend.
+ *
+ * Two exceptions, both in {@link GitHubMarkdown.tableFor} and neither in the
+ * serializer. Cells encode through the row schema, so a value smuggled past
+ * the types throws its `SchemaError`; and a column's own `format` function is
+ * called directly, so its totality is the caller's to guarantee. Well-typed
+ * rows through the default codec are total.
+ *
  * @example
  * ```ts
  * import { GitHubMarkdown } from "@effected/github-actions";
@@ -3073,6 +3244,19 @@ declare class GitHubMarkdown {
    * past the types throws the codec's `SchemaError` as a defect — same
    * posture as the serializer arm above, **not** a silent fallback.
    *
+   * This is the **only** member where a throw is reachable at runtime, and
+   * neither route is the serializer — see the no-wrapping remark on
+   * {@link GitHubMarkdown}. There are two:
+   *
+   * - the **codec**, for a value smuggled past the types. A caller holding
+   *   only well-typed rows (the normal case, and what the types express)
+   *   needs no wrapping; a caller feeding rows decoded from somewhere
+   *   untyped should decode through the schema rather than guard the render.
+   * - a column's own **`format`** function, which is called directly and
+   *   bypasses the codec entirely. Nothing here can make user code total, so
+   *   a `format` that can throw makes its render able to throw — keep
+   *   formatters total, or guard at the formatter rather than the render.
+   *
    * Only string-keyed fields become columns; symbol keys are not
    * enumerable table columns.
    *
@@ -4058,5 +4242,5 @@ declare class Secret {
   static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
 }
 //#endregion
-export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, ChildEnv, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, type PackageManagerInstallOptions, PackageManagerInstaller, PackageManagerInstallerError, type PackageManagerInstallerShape, type PathPrependEnv, type PathPrependOptions, ProcessId, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, type ToolDownloadOptions, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, WorkflowCommand, describeCause, projectCheckState };
+export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, ChildEnv, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, type PackageManagerInstallOptions, PackageManagerInstaller, PackageManagerInstallerError, type PackageManagerInstallerShape, type PathPrependEnv, type PathPrependOptions, ProcessId, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, type ToolDownloadOptions, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand, describeCause, projectCheckState };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github-actions",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"private": false,
 	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
 	"keywords": [