@effected/github-actions 0.1.0 → 0.2.0

package/ActionLogger.js

@@ -1,6 +1,6 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
 import { WorkflowCommand } from "./WorkflowCommand.js";
-import { Console, Context, Effect, Inspectable, Layer, LogLevel, Logger, References } from "effect";
+import { Console, Context, Effect, Exit, Inspectable, Layer, LogLevel, Logger, References } from "effect";
 
 //#region src/ActionLogger.ts
 /**
@@ -91,6 +91,10 @@ const renderEntry = (level, message, annotations) => {
 * @internal
 */
 const ActiveBuffer = Context.Reference("@effected/github-actions/ActiveBuffer", { defaultValue: () => null });
+/** Drop a transcript without writing it, so a green step stays quiet. */
+const discard = (state) => Effect.sync(() => {
+	state.entries.length = 0;
+});
 /** Write a transcript out and clear it, so a second flush is a no-op. */
 const flush = (state) => Effect.suspend(() => {
 	if (state.entries.length === 0) return Effect.void;
@@ -107,7 +111,7 @@ const make = Effect.gen(function* () {
 	const flushActive = Effect.flatMap(ActiveBuffer, (state) => state === null ? Effect.void : flush(state));
 	return {
 		group: (name, effect) => Effect.acquireUseRelease(Console.log(WorkflowCommand.group(name)), () => Effect.tapCause(effect, () => flushActive), () => Console.log(WorkflowCommand.endGroup())),
-		withBuffer: (label, effect) => Effect.gen(function* () {
+		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 = {
@@ -122,7 +126,7 @@ const make = Effect.gen(function* () {
 				}
 				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(() => flush(state)));
+			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)));
 		}),
 		notice: (message, properties = {}) => Console.log(WorkflowCommand.notice(message, properties)),
 		annotated: (properties, effect) => Effect.annotateLogs(effect, annotationRecord(properties))

package/ActionsIdentityToken.js

@@ -0,0 +1,61 @@
+import { OidcTokenIssuer } from "./OidcTokenIssuer.js";
+import { Effect, Layer } from "effect";
+import { IdentityToken, IdentityTokenError } from "@effected/sbom";
+
+//#region src/ActionsIdentityToken.ts
+/**
+* The Actions side of `@effected/sbom`'s inverted OIDC contract.
+*
+* @remarks
+* `@effected/sbom` declares `IdentityToken` — one method, one audience,
+* one redacted token — precisely so that signing does not drag the Actions
+* runtime into every consumer that only wants to emit an SBOM. This is the
+* layer that closes the inversion from the other side: it serves that contract
+* from the runner's own OIDC token service ({@link OidcTokenIssuer}), the same
+* arrangement as `@effected/workspaces` implementing `@effected/commands`'
+* `LocalExec`.
+*
+* The audience is forwarded verbatim. `SigstoreSigner` asks its identity
+* contract for the `sigstore` audience itself (`SIGSTORE_OIDC_AUDIENCE` is the
+* signing protocol's requirement, owned there), so nothing here — and nothing
+* in a consumer — needs to spell it.
+*
+* An `OidcTokenError` is rewrapped as `IdentityTokenError` with the
+* original preserved structurally in `cause`, so a refused exchange still says
+* which audience it was minting for **and** why the runner declined —
+* `reason: "unavailable"` almost always means the workflow is missing
+* `permissions: id-token: write`.
+*
+* @example
+* ```ts
+* import { ActionsIdentityToken, OidcTokenIssuer } from "@effected/github-actions";
+* import { SigstoreSigner } from "@effected/sbom";
+* import { Layer } from "effect";
+*
+* const signing = SigstoreSigner.layer.pipe(
+*   Layer.provide(ActionsIdentityToken.layer),
+*   Layer.provide(OidcTokenIssuer.layer),
+* );
+* ```
+*
+* @public
+*/
+var ActionsIdentityToken = class {
+	constructor() {}
+	/**
+	* `IdentityToken` served by the runner's OIDC token service.
+	*
+	* @remarks
+	* Requires {@link OidcTokenIssuer} rather than composing
+	* `OidcTokenIssuer.layer` in, so an action that already wired the issuer —
+	* every action using `ActionRuntime.layer` has its requirements at hand —
+	* does not construct a second one.
+	*/
+	static layer = Layer.effect(IdentityToken, Effect.map(OidcTokenIssuer, (issuer) => ({ token: (audience) => issuer.token(audience).pipe(Effect.mapError((cause) => new IdentityTokenError({
+		audience,
+		cause
+	}))) })));
+};
+
+//#endregion
+export { ActionsIdentityToken };

package/ActionsProvenance.js

@@ -0,0 +1,103 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { OidcTokenIssuer } from "./OidcTokenIssuer.js";
+import { Effect, Option } from "effect";
+import { SlsaProvenance } from "@effected/sbom";
+
+//#region src/ActionsProvenance.ts
+/**
+* The server URL a workflow on github.com runs against.
+*
+* @remarks
+* GHES runners export `GITHUB_SERVER_URL`; github.com runners do too, but a
+* program running outside a runner — or under a partial test environment —
+* legitimately sees it absent, and absence has a **correct answer** rather
+* than being an error. See {@link ActionsProvenance.capture}.
+*/
+const DEFAULT_SERVER_URL = "https://github.com";
+/**
+* The Actions side of `@effected/sbom`'s SLSA provenance constructor.
+*
+* @remarks
+* `SlsaProvenance.forGitHubWorkflow` is total and does the real work, but it
+* takes a camelCase input record — and the only input anyone inside a workflow
+* actually holds is the runner's own OIDC claims, spelled in GitHub's
+* snake_case claim names. The rename between the two is eleven all-string
+* fields, so transposing `repository_id` and `repository_owner_id` compiles,
+* passes every type check, and produces a validly signed attestation asserting
+* the **wrong** provenance. This module owns that rename once, on the same
+* `github-actions` ↔ `sbom` seam as {@link ActionsIdentityToken}: `sbom` must
+* not depend on the Actions runtime, so the adapter lives here, beside the
+* services it reads.
+*
+* The construct ends at the predicate. Assembling the in-toto statement,
+* signing it and uploading the bundle stay with the consumer — that pipeline
+* is deliberately consumer glue (see `@effected/sbom`'s `SigstoreSigner` and
+* `@effected/github`'s `Attestation.upload`).
+*
+* @example
+* ```ts
+* import { ActionsProvenance } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const provenance = yield* ActionsProvenance.capture();
+*   return provenance.runDetails.builder.id;
+* });
+* ```
+*
+* @public
+*/
+var ActionsProvenance = class {
+	constructor() {}
+	/**
+	* The current run's SLSA provenance, built from the runner's OIDC claims.
+	*
+	* @remarks
+	* Every field `GitHubWorkflowProvenance` declares is populated from
+	* {@link OidcClaims}, except `serverUrl`, which is read from
+	* `GITHUB_SERVER_URL` through {@link ActionEnvironment}'s `getOptional`
+	* with `https://github.com` as the default — **not** through the
+	* `GitHubContext` projection. The projection fails typed when a `GITHUB_*`
+	* variable is missing, and a missing server URL is not a failure: it has a
+	* correct default. GHES consumers set the variable, github.com consumers
+	* never should have to, and neither should think about it. (Upstream
+	* `@actions/attest` reads the same variable with no default and writes the
+	* literal string `undefined` into every URL it builds — the hazard
+	* `GitHubWorkflowProvenance.serverUrl` being a required field exists to
+	* prevent.)
+	*
+	* The audience is forwarded to {@link OidcTokenIssuerShape.claims}
+	* verbatim; the claims a provenance reads do not depend on it, so omitting
+	* it is fine and spends no extra token mint.
+	*
+	* An {@link OidcTokenError} passes through **untouched** — not caught, not
+	* defaulted, not wrapped. Whether attestation is mandatory or best-effort
+	* is the consumer's policy: an action that must not publish unattested
+	* lets the error propagate, and one that publishes anyway catches it at
+	* its own boundary. `reason: "unavailable"` almost always means the
+	* workflow is missing `permissions: id-token: write`.
+	*/
+	static capture = Effect.fn("ActionsProvenance.capture")(function* (audience) {
+		const issuer = yield* OidcTokenIssuer;
+		const env = yield* ActionEnvironment;
+		const claims = yield* issuer.claims(audience);
+		const serverUrl = Option.getOrElse(yield* env.getOptional("GITHUB_SERVER_URL"), () => DEFAULT_SERVER_URL);
+		return SlsaProvenance.forGitHubWorkflow({
+			serverUrl,
+			repository: claims.repository,
+			ref: claims.ref,
+			sha: claims.sha,
+			eventName: claims.event_name,
+			workflowRef: claims.workflow_ref,
+			jobWorkflowRef: claims.job_workflow_ref,
+			repositoryId: claims.repository_id,
+			repositoryOwnerId: claims.repository_owner_id,
+			runnerEnvironment: claims.runner_environment,
+			runId: claims.run_id,
+			runAttempt: claims.run_attempt
+		});
+	});
+};
+
+//#endregion
+export { ActionsProvenance };

package/CheckDocument.js

@@ -0,0 +1,193 @@
+import { CheckState } from "./CheckState.js";
+import { ManagedDocument } from "./ManagedDocument.js";
+import { Clock, Context, Duration, Effect, Latch, Layer, Ref, Schema, Semaphore } from "effect";
+
+//#region src/CheckDocument.ts
+/**
+* What a run knows about one of its checks: the authoritative state, and the
+* presentation facts a renderer projects into the document.
+*
+* @remarks
+* Only `state` is required. The rest exist because a status table needs them:
+* `title` when the display name differs from the registry key, `outcome` for
+* the one-line verdict cell, `url` for linking the check's name, and `detail`
+* for the per-check block a body region carries. A later report for the same
+* key **replaces** the whole entry — last write wins, per field and per check.
+*
+* @public
+*/
+var CheckReport = class extends Schema.Class("CheckReport")({
+	/** Where the check is now. The last reported state is the authoritative one. */
+	state: CheckState,
+	/** Display name, when it differs from the registry key. */
+	title: Schema.optionalKey(Schema.String),
+	/** A one-line verdict, e.g. `in progress...` or `3 packages ready`. */
+	outcome: Schema.optionalKey(Schema.String),
+	/** A pre-rendered markdown block of per-check detail. */
+	detail: Schema.optionalKey(Schema.String),
+	/** Where the check's name should link. */
+	url: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* Raised when the check document cannot be regenerated or written.
+*
+* @remarks
+* `render` — projecting the registry onto the document failed, almost always
+* because a reported `detail` contains a line the region scanner would read
+* as a marker; the underlying `ManagedDocumentError` rides in `cause`.
+* `sink` — the consumer's write effect failed; its error rides in `cause`.
+* Callers of `flush` branch on `kind`; the background reconciler never fails
+* a fiber with this — it logs and retries on the next report.
+*
+* @public
+*/
+var CheckDocumentError = class extends Schema.TaggedErrorClass()("CheckDocumentError", {
+	/** Which half failed: regenerating the document, or writing it. */
+	kind: Schema.Literals(["render", "sink"]),
+	/** The underlying failure. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return this.kind === "render" ? "The check document could not be regenerated from the reported state" : "Writing the check document failed";
+	}
+};
+/**
+* A living document of check state: an in-process registry the run reports
+* into, debounced onto a marker-delimited document, written through a narrow
+* sink.
+*
+* @remarks
+* **Push, not pull.** The run owns its checks and knows when they resolve;
+* nothing here polls GitHub. Consumers call `report` as states change, and a
+* background fiber projects the registry onto a {@link ManagedDocument} —
+* regions replaced from current state, so a check that resolves many times
+* updates its region in place instead of appending.
+*
+* The debounce is **trailing with a max-wait, never leading**: a burst of
+* reports coalesces into one write carrying the *final* state, and a steady
+* stream still surfaces progress every `maxWait`. A pass that renders
+* byte-identical text issues no write at all.
+*
+* `layer` mints fresh state per call — one layer per document. Bind it to a
+* `const` if two parts of a program must share one registry.
+*
+* @example
+* ```ts
+* import { CheckDocument, CheckReport, GitHubMarkdown } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const layer = CheckDocument.layer({
+*   namespace: "my-action",
+*   key: "release-validation",
+*   render: (checks) => [
+*     [
+*       "header",
+*       GitHubMarkdown.table(
+*         ["Check", "Outcome"],
+*         [...checks].map(([key, check]) => [key, check.outcome ?? check.state]),
+*       ),
+*     ],
+*   ],
+*   sink: (rendered) => Effect.log(rendered),
+* });
+*
+* const program = Effect.gen(function* () {
+*   const doc = yield* CheckDocument;
+*   yield* doc.report("build", CheckReport.make({ state: "running" }));
+*   yield* doc.report("build", CheckReport.make({ state: "pass", outcome: "clean" }));
+*   yield* doc.flush;
+* });
+* ```
+*
+* @public
+*/
+var CheckDocument = class CheckDocument extends Context.Service()("@effected/github-actions/CheckDocument") {
+	/**
+	* The reconciler over one document.
+	*
+	* @remarks
+	* Forks the debounce fiber into the layer's scope and registers a
+	* finalizer that flushes once more on the way out, so the scope closing
+	* mid-window cannot strand the final state. A background pass that fails
+	* logs a structured warning and leaves the registry intact — the next
+	* report retries it; only `flush` surfaces the typed error.
+	*/
+	static layer(options) {
+		return Layer.effect(CheckDocument, Effect.gen(function* () {
+			const quietMillis = Duration.toMillis(options.debounce?.quiet ?? "500 millis");
+			const maxWaitMillis = Math.max(Duration.toMillis(options.debounce?.maxWait ?? "3 seconds"), quietMillis);
+			const checksRef = yield* Ref.make(/* @__PURE__ */ new Map());
+			const writtenRef = yield* Ref.make(options.initial ?? "");
+			const versionRef = yield* Ref.make(0);
+			const signal = yield* Latch.make(false);
+			const gate = yield* Semaphore.make(1);
+			const reconcile = Effect.fn("CheckDocument.reconcile")(function* () {
+				const checks = yield* Ref.get(checksRef);
+				const current = yield* Ref.get(writtenRef);
+				const next = yield* (yield* ManagedDocument.parse({
+					namespace: options.namespace,
+					key: options.key,
+					text: current
+				}).pipe(Effect.mapError((cause) => new CheckDocumentError({
+					kind: "render",
+					cause
+				})))).withRegions(options.render(checks)).pipe(Effect.mapError((cause) => new CheckDocumentError({
+					kind: "render",
+					cause
+				})));
+				if (next.text === current) return;
+				yield* options.sink(next.text).pipe(Effect.timeout(options.sinkTimeout ?? "30 seconds"), Effect.mapError((cause) => new CheckDocumentError({
+					kind: "sink",
+					cause
+				})));
+				yield* Ref.set(writtenRef, next.text);
+			});
+			const flush = gate.withPermits(1)(reconcile());
+			const daemon = Effect.gen(function* () {
+				while (true) {
+					yield* signal.await;
+					yield* signal.close;
+					const start = yield* Clock.currentTimeMillis;
+					let settled = false;
+					while (!settled) {
+						const before = yield* Ref.get(versionRef);
+						yield* Effect.sleep(quietMillis);
+						const after = yield* Ref.get(versionRef);
+						const now = yield* Clock.currentTimeMillis;
+						settled = after === before || now - start >= maxWaitMillis;
+					}
+					yield* flush.pipe(Effect.catch((failure) => Effect.logWarning("CheckDocument reconcile failed; retrying on the next report", { kind: failure.kind })));
+				}
+			});
+			yield* Effect.addFinalizer(() => flush.pipe(Effect.catch((failure) => Effect.logWarning("CheckDocument final flush failed", { kind: failure.kind }))));
+			yield* Effect.forkScoped(daemon);
+			return {
+				report: Effect.fn("CheckDocument.report")(function* (check, entry) {
+					yield* Ref.update(checksRef, (current) => {
+						const next = new Map(current);
+						next.set(check, entry);
+						return next;
+					});
+					yield* Ref.update(versionRef, (count) => count + 1);
+					yield* signal.open;
+				}),
+				checks: Ref.get(checksRef),
+				flush
+			};
+		}));
+	}
+	/** An inert double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		report: overrides.report ?? (() => Effect.sync(() => unstubbed("report"))),
+		checks: overrides.checks ?? Effect.sync(() => unstubbed("checks")),
+		flush: overrides.flush ?? Effect.sync(() => unstubbed("flush"))
+	});
+	/** {@link CheckDocument.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(CheckDocument, CheckDocument.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`CheckDocument.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+
+//#endregion
+export { CheckDocument, CheckDocumentError, CheckReport };

package/CheckState.js

@@ -0,0 +1,75 @@
+import { Schema } from "effect";
+
+//#region src/CheckState.ts
+/**
+* The kit's check-state vocabulary.
+*
+* @remarks
+* Deliberately **wider than GitHub's own check-run conclusions**: `running` is
+* a first-class state rather than the absence of a conclusion, and
+* `user_interaction_required` names a release pipeline waiting on a human. A
+* check's lifecycle is a *sequence* of these states, and only the last one is
+* authoritative — resolution is not a terminal transition, so a check may run
+* `running`, `pass`, `running`, `fail` in order, and that means `fail`.
+*
+* Every state projects onto GitHub's check-run wire vocabulary through
+* {@link projectCheckState}. GitHub's `cancelled` conclusion has no
+* counterpart here on purpose: cancellation is something the runner does *to*
+* a run, not a state a pipeline reports about its own checks.
+*
+* @public
+*/
+const CheckState = Schema.Literals([
+	"running",
+	"pass",
+	"fail",
+	"warn",
+	"user_interaction_required",
+	"skipped",
+	"timeout"
+]);
+/**
+* Project a kit check state onto GitHub's check-run wire vocabulary.
+*
+* @remarks
+* The canonical mapping: `running` is `in_progress`; everything else is
+* `completed` with `pass → success`, `fail → failure`, `warn → neutral`
+* (GitHub has no warning conclusion, and `neutral` is its non-failing,
+* non-success verdict), `user_interaction_required → action_required`,
+* `skipped → skipped` and `timeout → timed_out`.
+*
+* @public
+*/
+const projectCheckState = (state) => {
+	switch (state) {
+		case "running": return { status: "in_progress" };
+		case "pass": return {
+			status: "completed",
+			conclusion: "success"
+		};
+		case "fail": return {
+			status: "completed",
+			conclusion: "failure"
+		};
+		case "warn": return {
+			status: "completed",
+			conclusion: "neutral"
+		};
+		case "user_interaction_required": return {
+			status: "completed",
+			conclusion: "action_required"
+		};
+		case "skipped": return {
+			status: "completed",
+			conclusion: "skipped"
+		};
+		case "timeout": return {
+			status: "completed",
+			conclusion: "timed_out"
+		};
+		default: throw new Error(`Unhandled CheckState: ${String(state)}`);
+	}
+};
+
+//#endregion
+export { CheckState, projectCheckState };

package/GitHubMarkdown.js

@@ -0,0 +1,197 @@
+import { Result, Schema, SchemaAST } from "effect";
+import { Code, Html, InlineCode, Link, List, ListItem, Markdown, Paragraph, Root, Table, TableCell, TableRow } from "@effected/markdown";
+
+//#region src/GitHubMarkdown.ts
+/**
+* A block node whose value passes through the serializer verbatim, which is
+* exactly how a pre-rendered markdown fragment must travel: GFM structure
+* around it is escaped, the fragment itself is not.
+*/
+const passthrough = (value) => Html.make({ value });
+/**
+* Serialize a tree the writer built itself.
+*
+* @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.
+*/
+const render = (root) => Result.getOrThrow(Markdown.stringifyResult(root)).trimEnd();
+const block = (node) => render(Root.make({ children: [node] }));
+/**
+* The fluent markdown writer for GitHub surfaces — PR comments, check-run
+* summaries, job summaries.
+*
+* @remarks
+* Every member takes **pre-rendered markdown** (links, emphasis, emoji — the
+* caller's fragments pass through verbatim) and returns a `string`, so
+* compositions read as plain string assembly. What the writer owns is the
+* *structure*: wherever a fragment could break the construct around it, the
+* output goes through `@effected/markdown`'s node classes and serializer
+* rather than string joining. A table cell carrying `>=1 || <2` renders with
+* its pipes escaped instead of shifting every column after it; a code block
+* whose content contains a fence gets a longer fence; inline code containing
+* a backtick gets a wider delimiter; a URL containing spaces or parentheses
+* is angle-bracketed.
+*
+* This module is the package's **only** importer of `@effected/markdown` — a
+* structural test pins that, on the same terms as the Azure confinement — so
+* an action that never renders markdown never links the engine.
+*
+* @example
+* ```ts
+* import { GitHubMarkdown } from "@effected/github-actions";
+*
+* const body = [
+*   GitHubMarkdown.heading("Release Validation"),
+*   GitHubMarkdown.table(["Check", "Outcome"], [["build", "✅ passed"]]),
+*   GitHubMarkdown.details("Logs", GitHubMarkdown.codeBlock(log, "text")),
+* ].join("\n\n");
+* ```
+*
+* @public
+*/
+var GitHubMarkdown = class GitHubMarkdown {
+	constructor() {}
+	/**
+	* A GFM table.
+	*
+	* @remarks
+	* Cells are pre-rendered markdown; the serializer escapes the pipes GFM
+	* would otherwise read as column breaks. Rows shorter than the header are
+	* padded with empty cells rather than shifting.
+	*/
+	static table(headers, rows) {
+		const inline = (value) => value.replace(/\r?\n/g, "<br>");
+		const cells = (values) => TableRow.make({ children: Array.from({ length: headers.length }, (_, index) => TableCell.make({ children: [passthrough(inline(values[index] ?? ""))] })) });
+		return block(Table.make({ children: [cells(headers), ...rows.map(cells)] }));
+	}
+	/**
+	* A GFM table whose columns are defined ONCE by a row schema.
+	*
+	* @remarks
+	* The schema is the single authority for the table's shape: column order
+	* is field declaration order, each header is the field's `title`
+	* annotation (fall back: the property name, overridable per column), and
+	* each cell is the field value's **encoded** string form — a branded or
+	* typed field projects through its own codec, so the vocabulary lives
+	* with the schema instead of being respelled at every call site, and a
+	* row can no longer transpose columns because it is a typed object, not
+	* a positional array.
+	*
+	* A field whose encoded side is not a string has no string projection to
+	* borrow; the type of `options` makes its column's `format` — and
+	* therefore `columns` and `options` themselves — required. An absent or
+	* `undefined` optional field renders as an empty cell without consulting
+	* codec or formatter.
+	*
+	* The renderer is a pure value: `render` maps current rows through
+	* {@link GitHubMarkdown.table}, so escaping is inherited and identical
+	* rows produce identical output. Rows are already-decoded values of the
+	* schema's type, so encoding them is total in practice; a value smuggled
+	* past the types throws the codec's `SchemaError` as a defect — same
+	* posture as the serializer arm above, **not** a silent fallback.
+	*
+	* Only string-keyed fields become columns; symbol keys are not
+	* enumerable table columns.
+	*
+	* @example
+	* ```ts
+	* import { GitHubMarkdown } from "@effected/github-actions";
+	* import { Schema } from "effect";
+	*
+	* const CheckRow = Schema.Struct({
+	*   name: Schema.String.annotate({ title: "Check" }),
+	*   outcome: Schema.Literals(["passed", "failed"]),
+	* });
+	* const checks = GitHubMarkdown.tableFor(CheckRow);
+	* const body = checks.render([{ name: "build", outcome: "passed" }]);
+	* ```
+	*/
+	static tableFor(schema, ...options) {
+		const overrides = options[0]?.columns ?? {};
+		const columns = Object.keys(schema.fields).map((key) => {
+			const field = schema.fields[key];
+			const column = overrides[key];
+			const format = column?.format;
+			const encode = format === void 0 ? Schema.encodeSync(field) : void 0;
+			return {
+				key,
+				header: column?.header ?? SchemaAST.resolveTitle(field.ast) ?? key,
+				cell: (value) => value === void 0 ? "" : format !== void 0 ? format(value) : encode?.(value) ?? ""
+			};
+		});
+		const headers = columns.map((column) => column.header);
+		return { render: (rows) => GitHubMarkdown.table(headers, rows.map((row) => columns.map((column) => column.cell(row[column.key])))) };
+	}
+	/** An ATX heading; the level defaults to `2`. */
+	static heading(text, level = 2) {
+		return `${"#".repeat(level)} ${text}`;
+	}
+	/** A link. URLs the destination cannot carry raw are angle-bracketed. */
+	static link(text, url) {
+		return block(Paragraph.make({ children: [Link.make({
+			url,
+			children: [passthrough(text)]
+		})] }));
+	}
+	/** Inline code. Content containing backticks widens the delimiter. */
+	static code(text) {
+		return block(Paragraph.make({ children: [InlineCode.make({ value: text })] }));
+	}
+	/** A fenced code block. Content containing a fence lengthens the fence. */
+	static codeBlock(content, language) {
+		return block(Code.make({
+			value: content,
+			fenceChar: "`",
+			...language === void 0 || language === "" ? {} : { lang: language }
+		}));
+	}
+	/**
+	* A list of pre-rendered markdown items.
+	*
+	* @remarks
+	* A multi-line item is indented onto continuation lines, so it stays part
+	* of its bullet instead of terminating the list.
+	*/
+	static list(items, options) {
+		const ordered = options?.ordered ?? false;
+		return block(List.make({
+			ordered,
+			...ordered ? { start: 1 } : {},
+			children: items.map((item) => ListItem.make({ children: [passthrough(item)] }))
+		}));
+	}
+	/**
+	* A collapsible `<details>` block.
+	*
+	* @remarks
+	* mdast has no details node, so this is the one construct the writer emits
+	* as raw HTML. The blank lines around `body` are what make GitHub render
+	* the markdown inside it; `summary` is HTML context — markdown is **not**
+	* rendered there, so bold a summary with `<strong>`, not `**`.
+	*/
+	static details(summary, body) {
+		return `<details>\n<summary>${summary}</summary>\n\n${body}\n\n</details>`;
+	}
+	/**
+	* Pre-rendered markdown, passed through by name.
+	*
+	* @remarks
+	* The identity function, deliberately: every writer member already treats
+	* its fragments as markdown, so `raw` adds no behavior — it adds the
+	* *statement* that a value is already rendered. Use it where a fragment
+	* from elsewhere enters a composition and a reader would otherwise wonder
+	* whether it still needs escaping. It replaces the `Html.make` idiom,
+	* which passes markdown through correctly but announces the wrong intent.
+	*/
+	static raw(markdown) {
+		return markdown;
+	}
+};
+
+//#endregion
+export { GitHubMarkdown };