@effected/github-actions 0.1.0 → 0.2.0

package/index.d.ts

@@ -2,6 +2,7 @@ import { NodeServices } from "@effect/platform-node";
 import { Cause, Config, ConfigProvider, Context, Duration, Effect, FileSystem, Layer, Logger, Option, Path, Redacted, Result, Schema } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
+import { IdentityToken, SlsaProvenance } from "@effected/sbom";
 import { BotIdentity, GitHubApp, GitHubClient, InstallationToken, PermissionLevel, RetryPolicy } from "@effected/github";
 //#region src/ActionEnvironment.d.ts
 declare const ActionEnvironmentError_base: Schema.Class<ActionEnvironmentError, Schema.TaggedStruct<"ActionEnvironmentError", {
@@ -237,6 +238,24 @@ declare class WorkflowCommand {
 }
 //#endregion
 //#region src/ActionLogger.d.ts
+/**
+ * Options for {@link ActionLoggerShape.withBuffer}.
+ *
+ * @public
+ */
+interface WithBufferOptions {
+  /**
+   * What happens to the captured transcript when the step **succeeds**.
+   *
+   * @remarks
+   * `"flush"` — the default — replays it, so a clean run still prints what it
+   * did. `"discard"` drops it, which is what keeps a green release log to one
+   * line per step: the transcript exists only as the failure report. A failure,
+   * a defect or an interruption flushes under either setting — the choice is
+   * only about what a success is worth in the log.
+   */
+  readonly onSuccess?: "flush" | "discard";
+}
 /**
  * The {@link ActionLogger} service shape.
  *
@@ -252,13 +271,18 @@ interface ActionLoggerShape {
    * Warnings and errors are **not** buffered — they go out as they happen, so a
    * long step still reports trouble while it is running. Everything at `Info`
    * and below is held and flushed on every exit path, including a defect or an
-   * interruption, so a clean run still prints its transcript.
+   * interruption, so a clean run still prints its transcript. A step that
+   * should be **quiet** when it succeeds passes
+   * `{ onSuccess: "discard" }` ({@link WithBufferOptions}); failure still
+   * spills the transcript either way.
    *
    * Buffering is skipped entirely when the runner has step debugging enabled or
    * the ambient minimum log level is already `Debug` or lower — someone asking
-   * for verbose output wants it live.
+   * for verbose output wants it live, and that overrides
+   * `onSuccess: "discard"` too: asking for debug output means wanting to see
+   * what a green step did.
    */
-  readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>, options?: WithBufferOptions) => Effect.Effect<A, E, R>;
   /**
    * Emit a `::notice::` annotation.
    *
@@ -1176,6 +1200,288 @@ declare class ActionInput {
   static readonly layerDefault: Layer.Layer<never>;
 }
 //#endregion
+//#region src/OidcTokenIssuer.d.ts
+declare const OidcTokenError_base: Schema.Class<OidcTokenError, Schema.TaggedStruct<"OidcTokenError", {
+  /**
+   * `unavailable` — the runner did not publish the token-service variables,
+   * which almost always means the workflow is missing `permissions: id-token:
+   * write`. `requestFailed` — the token service could not be reached or refused
+   * the request. `malformedResponse` — it answered with something that is not a
+   * token envelope. `malformedToken` — the token is not a decodable JWT.
+   * `missingClaims` — it decoded, but without the claims a provenance statement
+   * needs.
+   */
+  readonly reason: Schema.Literals<readonly ["unavailable", "requestFailed", "malformedResponse", "malformedToken", "missingClaims"]>;
+  /** What was wrong, in one line. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** The HTTP status, when the token service answered. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when an OIDC token cannot be issued or read.
+ *
+ * @public
+ */
+declare class OidcTokenError extends OidcTokenError_base {
+  get message(): string;
+}
+declare const OidcClaims_base: Schema.Class<OidcClaims, Schema.Struct<{
+  /** The issuer, e.g. `https://token.actions.githubusercontent.com`. */
+  readonly iss: Schema.String;
+  /** The full ref the workflow ran on. */
+  readonly ref: Schema.String;
+  /** The commit. */
+  readonly sha: Schema.String;
+  /** `owner/repo`. */
+  readonly repository: Schema.String;
+  /** The event that triggered the run. */
+  readonly event_name: Schema.String;
+  /** The reusable-workflow ref, which is what a verifier pins against. */
+  readonly job_workflow_ref: Schema.String;
+  /** The calling workflow's ref. */
+  readonly workflow_ref: Schema.String;
+  /** The numeric repository id, as a string. */
+  readonly repository_id: Schema.String;
+  /** The numeric owner id, as a string. */
+  readonly repository_owner_id: Schema.String;
+  /** `github-hosted` or `self-hosted`. */
+  readonly runner_environment: Schema.String;
+  /** The run id, as a string. */
+  readonly run_id: Schema.String;
+  /** The run attempt, as a string. */
+  readonly run_attempt: Schema.String;
+}>, {}>;
+/**
+ * The claims a GitHub Actions OIDC token carries about the workflow that ran.
+ *
+ * @remarks
+ * The field names are GitHub's own JWT claim names, kept verbatim rather than
+ * translated to the kit's casing. They are an **external vocabulary** — the
+ * same strings that appear in a SLSA provenance predicate and in every
+ * published example of an Actions OIDC policy — and renaming them would put a
+ * translation layer between a consumer and the specification they are reading.
+ *
+ * @public
+ */
+declare class OidcClaims extends OidcClaims_base {}
+/**
+ * The {@link OidcTokenIssuer} service shape.
+ *
+ * @public
+ */
+interface OidcTokenIssuerShape {
+  /**
+   * Request an ID token, optionally bound to an audience.
+   *
+   * @remarks
+   * Omitting the audience sends no `audience` parameter at all, matching
+   * `@actions/core.getIDToken` — the runner's default audience is not the empty
+   * string.
+   */
+  readonly token: (audience?: string) => Effect.Effect<Redacted.Redacted<string>, OidcTokenError>;
+  /**
+   * The token's claims, decoded.
+   *
+   * @remarks
+   * **The signature is deliberately not verified**, for three reasons that are
+   * recorded so nobody "fixes" it:
+   *
+   * 1. The token comes from the runner's own token-service endpoint over TLS.
+   *    The transport is the trust boundary, and the process asking for the
+   *    token is the process that received it.
+   * 2. The claims populate a provenance predicate, not a trust decision.
+   *    Nothing branches on them for authorization; they are recorded as
+   *    attested facts about the workflow that ran.
+   * 3. Verifying would need a JWKS fetch, which turns a decode into a network
+   *    call — untestable without a fixture server, and dependent on GitHub's
+   *    key endpoint being reachable at attestation time.
+   *
+   * A consumer that needs a *verified* token needs a different operation with a
+   * different name and a different error channel, not an option on this one.
+   *
+   * Claims are on the surface rather than left to the call site because that is
+   * what makes the provenance path reachable in a test: a double built with
+   * {@link OidcTokenIssuer.layerFor} answers with real, decodable claims, where
+   * the synthetic non-JWT its predecessor returned made every consumer's
+   * `decodeJwtClaims` yield nothing and silently skipped the path under test.
+   */
+  readonly claims: (audience?: string) => Effect.Effect<OidcClaims, OidcTokenError>;
+}
+declare const OidcTokenIssuer_base: Context.ServiceClass<OidcTokenIssuer, "@effected/github-actions/OidcTokenIssuer", OidcTokenIssuerShape>;
+/**
+ * The runner's OIDC token service.
+ *
+ * @remarks
+ * Lives here rather than with attestation because it reads
+ * `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL`, which
+ * exist only when a workflow declares `permissions: id-token: write` — that is
+ * a fact about the runner, not about signing.
+ *
+ * @example
+ * ```ts
+ * import { OidcTokenIssuer } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const issuer = yield* OidcTokenIssuer;
+ *   const claims = yield* issuer.claims("sigstore");
+ *   return claims.job_workflow_ref;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class OidcTokenIssuer extends OidcTokenIssuer_base {
+  static readonly layer: Layer.Layer<OidcTokenIssuer, never, ActionEnvironment | HttpClient.HttpClient>;
+  /**
+   * An **unsigned** JWT carrying these claims.
+   *
+   * @remarks
+   * For building test doubles, and nothing else: the signature segment is a
+   * placeholder, so this token would fail any verifier. It exists because the
+   * alternative — a double returning a synthetic non-JWT — is what made the
+   * provenance path structurally unreachable in the source package, drawing
+   * four separate apologetic comments from one consumer.
+   */
+  static readonly unsignedTokenFor: (claims: OidcClaims) => Redacted.Redacted<string>;
+  /** A test double. Unstubbed members die rather than answering with a non-token. */
+  static readonly makeTest: (overrides?: Partial<OidcTokenIssuerShape>) => OidcTokenIssuerShape;
+  /** {@link OidcTokenIssuer.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<OidcTokenIssuerShape>) => Layer.Layer<OidcTokenIssuer>;
+  /**
+   * A double that answers with these claims, consistently on both members.
+   *
+   * @remarks
+   * `token()` returns a real decodable JWT built from the same claims
+   * `claims()` returns, so a consumer that decodes the token itself and a
+   * consumer that asks the service both see the same thing. A double whose two
+   * members can disagree is how a test proves a path works while production
+   * takes the other one.
+   */
+  static readonly layerFor: (claims: OidcClaims) => Layer.Layer<OidcTokenIssuer>;
+}
+//#endregion
+//#region src/ActionsIdentityToken.d.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
+ */
+declare class ActionsIdentityToken {
+  private 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 readonly layer: Layer.Layer<IdentityToken, never, OidcTokenIssuer>;
+}
+//#endregion
+//#region src/ActionsProvenance.d.ts
+/**
+ * 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
+ */
+declare class ActionsProvenance {
+  private 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 readonly capture: (audience?: string) => Effect.Effect<SlsaProvenance, OidcTokenError, OidcTokenIssuer | ActionEnvironment>;
+}
+//#endregion
 //#region src/Artifact.d.ts
 declare const ArtifactError_base: Schema.Class<ArtifactError, Schema.TaggedStruct<"ArtifactError", {
   /**
@@ -1625,55 +1931,338 @@ declare class GitHubCacheBlobStore {
   static readonly layerWith: (transfer: DataBlobTransfer) => Layer.Layer<BlobStore, never, HttpClient.HttpClient | ActionEnvironment>;
 }
 //#endregion
-//#region src/DetachedProcess.d.ts
-declare const DetachedProcessError_base: Schema.Class<DetachedProcessError, Schema.TaggedStruct<"DetachedProcessError", {
-  /**
-   * `logUnavailable` — the log file could not be opened, so there is nowhere
-   * for the child's output to go. `spawnFailed` — the child did not start.
-   * `invalidPid` — a non-positive pid was handed to {@link DetachedProcess.reap};
-   * see there for why this is the most important value in the module.
-   * `signalFailed` — the signal was refused, e.g. the process belongs to
-   * another user. `notReady` — the readiness probe never held.
-   */
-  readonly reason: Schema.Literals<readonly ["logUnavailable", "spawnFailed", "invalidPid", "signalFailed", "notReady"]>;
-  /** The pid involved, when one is. */
-  readonly pid: Schema.optionalKey<Schema.Number>;
-  /** The path involved, when one is. */
-  readonly path: Schema.optionalKey<Schema.String>;
-  /** The underlying failure, preserved structurally. */
+//#region src/CheckDocument.d.ts
+declare const CheckReport_base: Schema.Class<CheckReport, Schema.Struct<{
+  /** Where the check is now. The last reported state is the authoritative one. */
+  readonly state: Schema.Literals<readonly ["running", "pass", "fail", "warn", "user_interaction_required", "skipped", "timeout"]>;
+  /** Display name, when it differs from the registry key. */
+  readonly title: Schema.optionalKey<Schema.String>;
+  /** A one-line verdict, e.g. `in progress...` or `3 packages ready`. */
+  readonly outcome: Schema.optionalKey<Schema.String>;
+  /** A pre-rendered markdown block of per-check detail. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** Where the check's name should link. */
+  readonly url: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * 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
+ */
+declare class CheckReport extends CheckReport_base {}
+declare const CheckDocumentError_base: Schema.Class<CheckDocumentError, Schema.TaggedStruct<"CheckDocumentError", {
+  /** Which half failed: regenerating the document, or writing it. */
+  readonly kind: Schema.Literals<readonly ["render", "sink"]>;
+  /** The underlying failure. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Raised when a detached child cannot be started, waited for, or reaped.
+ * 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
  */
-declare class DetachedProcessError extends DetachedProcessError_base {
+declare class CheckDocumentError extends CheckDocumentError_base {
   get message(): string;
 }
 /**
- * The schema a pid crosses the phase boundary through.
+ * How a rendered document leaves the process: the narrow sink contract.
  *
  * @remarks
- * A pid is persisted in `GITHUB_STATE` by `main` and read back by `post`, which
- * means it makes the round trip as **text**. This is the boundary check on the
- * way back in: a truncated file, an absent key or a `Number("")` all decode to
- * `0`, and `0` is not a process — it is the current process's whole group.
- * Refusing it here means the bad value never reaches {@link DetachedProcess.reap}
- * in the first place, and reap's own guard is the second of two defenses rather
- * than the only one.
+ * One rendered document in, one write effect out — nothing else. That is
+ * what lets the sticky PR comment (`PullRequestComment.upsert`), the PR
+ * description (`PATCH` on the pull request) and a test's recording `Ref` all
+ * fit the same reconciler. The success value is ignored; a failure surfaces
+ * as {@link CheckDocumentError} with `kind: "sink"`. Provide any services the
+ * write needs when constructing the sink — the reconciler runs it as given.
  *
- * **The brand is core's**, from `ChildProcessSpawner` — the subprocess
- * vocabulary belongs to core and this package does not get to re-declare it.
- * What core does not have is a *validating* way to reconstruct one: its
- * constructor is `Brand.nominal`, which applies no runtime check, so
- * `ChildProcessSpawner.ProcessId(0)` succeeds. That is exactly right for a pid
- * the spawner just produced, and exactly wrong for a pid that has been through a
- * text file. This schema is that missing check, and it decodes to core's type so
- * the two are interchangeable.
+ * @public
+ */
+type CheckDocumentSink = (rendered: string) => Effect.Effect<unknown, unknown>;
+/**
+ * Options for {@link CheckDocument.layer}.
  *
- * @example
- * ```ts
+ * @public
+ */
+interface CheckDocumentOptions {
+  /** The managed document's namespace, e.g. your action's name. */
+  readonly namespace: string;
+  /** Which document, within that namespace. */
+  readonly key: string;
+  /**
+   * The document text to reconcile against initially — a PR body fetched
+   * once at startup, so human content outside the managed regions survives.
+   * Defaults to empty: a fresh document.
+   */
+  readonly initial?: string | undefined;
+  /**
+   * The pure projection from registry state to region entries.
+   *
+   * @remarks
+   * Called with the full snapshot on every reconcile pass; returns the
+   * regions to replace, keyed however the consumer's document is laid out —
+   * typically one region per check plus a shared status table. It must be a
+   * pure function of the snapshot: rendering the same state twice must
+   * produce the same entries, because byte-identical output is what
+   * suppresses the write.
+   */
+  readonly render: (checks: ReadonlyMap<string, CheckReport>) => ReadonlyArray<readonly [key: string, content: string]>;
+  /** Where the rendered document goes. */
+  readonly sink: CheckDocumentSink;
+  /**
+   * Debounce parameters: `quiet` is the trailing settle window, `maxWait`
+   * the staleness bound under a steady stream of reports. Defaults: 500
+   * milliseconds and 3 seconds.
+   */
+  readonly debounce?: {
+    readonly quiet?: Duration.Input | undefined;
+    readonly maxWait?: Duration.Input | undefined;
+  } | undefined;
+  /**
+   * How long one sink write may run before the pass fails with
+   * `kind: "sink"`. Default: 30 seconds.
+   *
+   * @remarks
+   * The reconciler serializes passes behind one permit, and the finalizer's
+   * last flush waits on that same permit — so a sink that never resolves
+   * would otherwise stall every later pass AND scope teardown. The bound
+   * turns a hung write into the ordinary sink failure path: a background
+   * pass logs and retries on the next report, `flush` surfaces the typed
+   * error.
+   */
+  readonly sinkTimeout?: Duration.Input | undefined;
+}
+/**
+ * The check-run → document reconciler's surface.
+ *
+ * @public
+ */
+interface CheckDocumentShape {
+  /**
+   * Record a check's current state and schedule a reconcile.
+   *
+   * @remarks
+   * Never fails and never blocks on the write — the state lands in the
+   * registry, and the debounced background pass projects it. Reporting the
+   * same key again replaces the entry; resolution is **not** terminal, so
+   * `pass` followed by `fail` leaves `fail` even inside one debounce window.
+   */
+  readonly report: (check: string, report: CheckReport) => Effect.Effect<void>;
+  /** The registry as of now, in first-report order. */
+  readonly checks: Effect.Effect<ReadonlyMap<string, CheckReport>>;
+  /**
+   * Reconcile immediately, skipping the debounce.
+   *
+   * @remarks
+   * Rendering unchanged state issues no write. Call it at the end of a run;
+   * the layer's finalizer also runs it, so the last burst of reports lands
+   * even when the scope closes inside the quiet window.
+   */
+  readonly flush: Effect.Effect<void, CheckDocumentError>;
+}
+declare const CheckDocument_base: Context.ServiceClass<CheckDocument, "@effected/github-actions/CheckDocument", CheckDocumentShape>;
+/**
+ * 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
+ */
+declare class CheckDocument extends CheckDocument_base {
+  /**
+   * 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: CheckDocumentOptions): Layer.Layer<CheckDocument>;
+  /** An inert double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<CheckDocumentShape>) => CheckDocumentShape;
+  /** {@link CheckDocument.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<CheckDocumentShape>) => Layer.Layer<CheckDocument>;
+}
+//#endregion
+//#region src/CheckState.d.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
+ */
+declare const CheckState: Schema.Literals<readonly ["running", "pass", "fail", "warn", "user_interaction_required", "skipped", "timeout"]>;
+/**
+ * The type of `CheckState`.
+ *
+ * @public
+ */
+type CheckState = typeof CheckState.Type;
+/**
+ * The check-run conclusions the kit vocabulary can produce.
+ *
+ * @remarks
+ * A subset of GitHub's conclusion set, spelled structurally so a pure
+ * vocabulary module does not put `@effected/github` — and through it the
+ * octokit runtime — on its import graph. A structural assertion in the test
+ * suite pins these literals against `CheckConclusion` in `@effected/github`,
+ * so drift between the two spellings fails a test rather than a consumer.
+ *
+ * @public
+ */
+type CheckRunConclusion = "success" | "failure" | "neutral" | "skipped" | "timed_out" | "action_required";
+/**
+ * A `CheckState` on GitHub's check-run wire: a status, and a conclusion
+ * exactly when the status is `completed`.
+ *
+ * @remarks
+ * A discriminated union rather than two optional fields, because the wire
+ * protocol's own invariant is conditional: an in-progress check run *has* no
+ * conclusion, and a completed one always does.
+ *
+ * @public
+ */
+type CheckRunProjection = {
+  readonly status: "in_progress";
+} | {
+  readonly status: "completed";
+  readonly conclusion: CheckRunConclusion;
+};
+/**
+ * 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
+ */
+declare const projectCheckState: (state: CheckState) => CheckRunProjection;
+//#endregion
+//#region src/DetachedProcess.d.ts
+declare const DetachedProcessError_base: Schema.Class<DetachedProcessError, Schema.TaggedStruct<"DetachedProcessError", {
+  /**
+   * `logUnavailable` — the log file could not be opened, so there is nowhere
+   * for the child's output to go. `spawnFailed` — the child did not start.
+   * `invalidPid` — a non-positive pid was handed to {@link DetachedProcess.reap};
+   * see there for why this is the most important value in the module.
+   * `signalFailed` — the signal was refused, e.g. the process belongs to
+   * another user. `notReady` — the readiness probe never held.
+   */
+  readonly reason: Schema.Literals<readonly ["logUnavailable", "spawnFailed", "invalidPid", "signalFailed", "notReady"]>;
+  /** The pid involved, when one is. */
+  readonly pid: Schema.optionalKey<Schema.Number>;
+  /** The path involved, when one is. */
+  readonly path: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a detached child cannot be started, waited for, or reaped.
+ *
+ * @public
+ */
+declare class DetachedProcessError extends DetachedProcessError_base {
+  get message(): string;
+}
+/**
+ * The schema a pid crosses the phase boundary through.
+ *
+ * @remarks
+ * A pid is persisted in `GITHUB_STATE` by `main` and read back by `post`, which
+ * means it makes the round trip as **text**. This is the boundary check on the
+ * way back in: a truncated file, an absent key or a `Number("")` all decode to
+ * `0`, and `0` is not a process — it is the current process's whole group.
+ * Refusing it here means the bad value never reaches {@link DetachedProcess.reap}
+ * in the first place, and reap's own guard is the second of two defenses rather
+ * than the only one.
+ *
+ * **The brand is core's**, from `ChildProcessSpawner` — the subprocess
+ * vocabulary belongs to core and this package does not get to re-declare it.
+ * What core does not have is a *validating* way to reconstruct one: its
+ * constructor is `Brand.nominal`, which applies no runtime check, so
+ * `ChildProcessSpawner.ProcessId(0)` succeeds. That is exactly right for a pid
+ * the spawner just produced, and exactly wrong for a pid that has been through a
+ * text file. This schema is that missing check, and it decodes to core's type so
+ * the two are interchangeable.
+ *
+ * @example
+ * ```ts
  * import { ActionState, DetachedProcess, ProcessId } from "@effected/github-actions";
  * import { Effect } from "effect";
  *
@@ -1896,6 +2485,230 @@ declare class DryRun extends DryRun_base {
   static readonly layerTest: (overrides?: Partial<DryRunShape>) => Layer.Layer<DryRun>;
 }
 //#endregion
+//#region src/GitHubMarkdown.d.ts
+/**
+ * A heading level GitHub renders, `1` through `6`.
+ *
+ * @public
+ */
+type GitHubHeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Options for {@link GitHubMarkdown.list}.
+ *
+ * @public
+ */
+interface GitHubListOptions {
+  /** Render `1.`-numbered items instead of bullets. */
+  readonly ordered?: boolean | undefined;
+}
+/**
+ * The row-schema constraint {@link GitHubMarkdown.tableFor} accepts: any
+ * schema exposing a struct field map — `Schema.Struct` and `Schema.Class`
+ * both qualify.
+ *
+ * @public
+ */
+type GitHubRowSchema = Schema.Constraint & {
+  readonly fields: Schema.Struct.Fields;
+};
+/**
+ * The field keys of a row schema whose column REQUIRES an explicit
+ * `format`: fields whose encoded side is not a string (their codec has no
+ * string projection to borrow), and fields whose encoding needs services
+ * (a sync cell render cannot provide them).
+ *
+ * @public
+ */
+type GitHubSchemaTableFormatRequiredKeys<Fields extends Schema.Struct.Fields> = { [K in keyof Fields]: [Fields[K]["Encoded"]] extends [string | undefined] ? [Fields[K]["EncodingServices"]] extends [never] ? never : K : K; }[keyof Fields];
+/**
+ * Per-column configuration for {@link GitHubMarkdown.tableFor}.
+ *
+ * @public
+ */
+interface GitHubSchemaTableColumn<Value> {
+  /**
+   * The column header, overriding the field schema's `title` annotation
+   * and the field-name fallback. Pre-rendered markdown, like every cell.
+   */
+  readonly header?: string | undefined;
+  /**
+   * Render a cell from the decoded field value instead of encoding it
+   * through the field's codec. Required — by type — for a field whose
+   * encoded side is not a string.
+   */
+  readonly format?: ((value: Value) => string) | undefined;
+}
+/**
+ * {@link GitHubSchemaTableColumn} with the `format` obligation discharged —
+ * the entry shape a non-string-encoded field demands.
+ *
+ * @public
+ */
+interface GitHubSchemaTableFormattedColumn<Value> extends GitHubSchemaTableColumn<Value> {
+  readonly format: (value: Value) => string;
+}
+/**
+ * The per-field column map for {@link GitHubMarkdown.tableFor}: entries are
+ * optional except where the field's encoded side is not a string, where the
+ * entry — and its `format` — are required.
+ *
+ * @public
+ */
+type GitHubSchemaTableColumns<Fields extends Schema.Struct.Fields> = { readonly [K in GitHubSchemaTableFormatRequiredKeys<Fields>]: GitHubSchemaTableFormattedColumn<Exclude<Fields[K]["Type"], undefined>>; } & { readonly [K in Exclude<keyof Fields, GitHubSchemaTableFormatRequiredKeys<Fields>>]?: GitHubSchemaTableColumn<Exclude<Fields[K]["Type"], undefined>>; };
+/**
+ * Options for {@link GitHubMarkdown.tableFor}. The whole bag is optional
+ * exactly when every field's encoded side is a string; one field without a
+ * string projection makes `columns` — and the entry carrying its `format` —
+ * required.
+ *
+ * @public
+ */
+type GitHubSchemaTableOptions<Fields extends Schema.Struct.Fields> = [GitHubSchemaTableFormatRequiredKeys<Fields>] extends [never] ? {
+  readonly columns?: GitHubSchemaTableColumns<Fields> | undefined;
+} : {
+  readonly columns: GitHubSchemaTableColumns<Fields>;
+};
+/**
+ * A renderer minted by {@link GitHubMarkdown.tableFor}: columns are fixed by
+ * the schema, rows are supplied at each render.
+ *
+ * @public
+ */
+interface GitHubSchemaTable<Row> {
+  /**
+   * Render the current rows as a GFM table. Pure and repeatable — identical
+   * rows produce identical output, so re-rendering from changed state is
+   * just calling it again.
+   */
+  render(rows: ReadonlyArray<Row>): string;
+}
+/**
+ * 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
+ */
+declare class GitHubMarkdown {
+  private 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: ReadonlyArray<string>, rows: ReadonlyArray<ReadonlyArray<string>>): string;
+  /**
+   * 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<S extends GitHubRowSchema>(schema: S, ...options: [GitHubSchemaTableFormatRequiredKeys<S["fields"]>] extends [never] ? [options?: GitHubSchemaTableOptions<S["fields"]>] : [options: GitHubSchemaTableOptions<S["fields"]>]): GitHubSchemaTable<S["Type"]>;
+  /** An ATX heading; the level defaults to `2`. */
+  static heading(text: string, level?: GitHubHeadingDepth): string;
+  /** A link. URLs the destination cannot carry raw are angle-bracketed. */
+  static link(text: string, url: string): string;
+  /** Inline code. Content containing backticks widens the delimiter. */
+  static code(text: string): string;
+  /** A fenced code block. Content containing a fence lengthens the fence. */
+  static codeBlock(content: string, language?: string): string;
+  /**
+   * 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: ReadonlyArray<string>, options?: GitHubListOptions): string;
+  /**
+   * 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: string, body: string): string;
+  /**
+   * 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: string): string;
+}
+//#endregion
 //#region src/GitHubToken.d.ts
 declare const GitHubTokenError_base: Schema.Class<GitHubTokenError, Schema.TaggedStruct<"GitHubTokenError", {
   /**
@@ -2087,167 +2900,183 @@ declare class GitHubToken {
   static readonly dispose: (options?: ReadOptions | undefined) => Effect.Effect<void, ActionStateError | import("@effected/github").GitHubAppError, ActionState | GitHubApp>;
 }
 //#endregion
-//#region src/OidcTokenIssuer.d.ts
-declare const OidcTokenError_base: Schema.Class<OidcTokenError, Schema.TaggedStruct<"OidcTokenError", {
-  /**
-   * `unavailable` — the runner did not publish the token-service variables,
-   * which almost always means the workflow is missing `permissions: id-token:
-   * write`. `requestFailed` — the token service could not be reached or refused
-   * the request. `malformedResponse` — it answered with something that is not a
-   * token envelope. `malformedToken` — the token is not a decodable JWT.
-   * `missingClaims` — it decoded, but without the claims a provenance statement
-   * needs.
-   */
-  readonly reason: Schema.Literals<readonly ["unavailable", "requestFailed", "malformedResponse", "malformedToken", "missingClaims"]>;
-  /** What was wrong, in one line. */
-  readonly detail: Schema.optionalKey<Schema.String>;
-  /** The HTTP status, when the token service answered. */
-  readonly status: Schema.optionalKey<Schema.Number>;
-  /** The underlying failure, preserved structurally. */
-  readonly cause: Schema.optionalKey<Schema.Defect>;
+//#region src/ManagedDocument.d.ts
+declare const ManagedDocumentError_base: Schema.Class<ManagedDocumentError, Schema.TaggedStruct<"ManagedDocumentError", {
+  /** Which ambiguity or refusal was found. */
+  readonly kind: Schema.Literals<readonly ["unterminatedRegion", "orphanedEnd", "overlappingRegions", "duplicateRegion", "markerInContent", "duplicateDeclaration"]>;
+  /** 1-based line of the offending marker, for the structural kinds. */
+  readonly line: Schema.optionalKey<Schema.Number>;
+  /** The region key involved, when the failure names one. */
+  readonly key: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Raised when an OIDC token cannot be issued or read.
+ * Raised when a managed document cannot be read or regenerated without
+ * guessing.
+ *
+ * @remarks
+ * The four structural kinds (`unterminatedRegion`, `orphanedEnd`,
+ * `overlappingRegions`, `duplicateRegion`) surface at parse time and name an
+ * ambiguity whose silent resolution would corrupt content a human wrote by
+ * hand. The two declaration kinds surface when regions are applied:
+ * `markerInContent` refuses region content that itself contains a line the
+ * scanner would read as a region marker, and `duplicateDeclaration` refuses
+ * one call that states two intentions for the same region.
  *
  * @public
  */
-declare class OidcTokenError extends OidcTokenError_base {
+declare class ManagedDocumentError extends ManagedDocumentError_base {
   get message(): string;
 }
-declare const OidcClaims_base: Schema.Class<OidcClaims, Schema.Struct<{
-  /** The issuer, e.g. `https://token.actions.githubusercontent.com`. */
-  readonly iss: Schema.String;
-  /** The full ref the workflow ran on. */
-  readonly ref: Schema.String;
-  /** The commit. */
-  readonly sha: Schema.String;
-  /** `owner/repo`. */
-  readonly repository: Schema.String;
-  /** The event that triggered the run. */
-  readonly event_name: Schema.String;
-  /** The reusable-workflow ref, which is what a verifier pins against. */
-  readonly job_workflow_ref: Schema.String;
-  /** The calling workflow's ref. */
-  readonly workflow_ref: Schema.String;
-  /** The numeric repository id, as a string. */
-  readonly repository_id: Schema.String;
-  /** The numeric owner id, as a string. */
-  readonly repository_owner_id: Schema.String;
-  /** `github-hosted` or `self-hosted`. */
-  readonly runner_environment: Schema.String;
-  /** The run id, as a string. */
-  readonly run_id: Schema.String;
-  /** The run attempt, as a string. */
-  readonly run_attempt: Schema.String;
-}>, {}>;
 /**
- * The claims a GitHub Actions OIDC token carries about the workflow that ran.
- *
- * @remarks
- * The field names are GitHub's own JWT claim names, kept verbatim rather than
- * translated to the kit's casing. They are an **external vocabulary** — the
- * same strings that appear in a SLSA provenance predicate and in every
- * published example of an Actions OIDC policy — and renaming them would put a
- * translation layer between a consumer and the specification they are reading.
+ * Options identifying a managed document inside a text that may not carry one
+ * yet.
  *
  * @public
  */
-declare class OidcClaims extends OidcClaims_base {}
+interface ManagedDocumentSource {
+  /** Whose document this is, e.g. your action's name. */
+  readonly namespace: string;
+  /** Which document, within that namespace. */
+  readonly key: string;
+  /**
+   * The current text — a fetched comment body, a PR description — or absent
+   * when there is nothing yet. An absent text and an empty one mean the same
+   * thing: a fresh document.
+   */
+  readonly text?: string | undefined;
+}
+declare const ManagedDocument_base: Schema.Class<ManagedDocument, Schema.Struct<{
+  /** Whose document this is. */
+  readonly namespace: Schema.String;
+  /** Which document, within that namespace. */
+  readonly key: Schema.String;
+  /** The document's full text, sentinel and regions included. */
+  readonly text: Schema.String;
+}>, {}>;
 /**
- * The {@link OidcTokenIssuer} service shape.
+ * A marker-delimited document: named regions a tool owns, inside text a human
+ * may also edit.
+ *
+ * @remarks
+ * The one primitive behind both the sticky PR comment and the managed PR
+ * description. A sentinel HTML comment (`<!-- namespace:key -->`) identifies
+ * the document; each region is delimited by HTML-comment markers keyed
+ * `namespace.key.region`; and everything outside the managed regions is
+ * preserved byte-for-byte on regeneration. Regions are **replaced from
+ * current state, never appended** — applying the same region twice yields one
+ * region carrying the latest content, which is what makes a check that
+ * resolves many times safe to re-render.
+ *
+ * The region engine is `@effected/templates`' pure `SectionDocument` —
+ * reused, not reinvented — fixed to the HTML comment style and a
+ * region-specific phrase. Everything here is string → string; the GitHub
+ * write path composes this with `PullRequestComment` (whose `CommentMarker`
+ * renders the *same* sentinel for the same namespace and key) or a PR-body
+ * update in `@effected/github`.
+ *
+ * Construct with {@link ManagedDocument.parseResult} — create-or-update in
+ * one call, so the consumer never branches on whether the document exists
+ * yet. `ManagedDocument.make` is the raw schema constructor and performs no
+ * structural validation.
+ *
+ * @example
+ * ```ts
+ * import { ManagedDocument } from "@effected/github-actions";
+ * import { Result } from "effect";
+ *
+ * const doc = ManagedDocument.parseResult({ namespace: "my-action", key: "release", text: fetched });
+ * if (Result.isSuccess(doc)) {
+ *   const next = doc.success.withRegionsResult([
+ *     ["header", "## Validating Release"],
+ *     ["footer", "generated by my-action"],
+ *   ]);
+ * }
+ * ```
  *
  * @public
  */
-interface OidcTokenIssuerShape {
+declare class ManagedDocument extends ManagedDocument_base {
   /**
-   * Request an ID token, optionally bound to an audience.
+   * Read a document out of existing text, or begin a fresh one.
    *
    * @remarks
-   * Omitting the audience sends no `audience` parameter at all, matching
-   * `@actions/core.getIDToken` — the runner's default audience is not the empty
-   * string.
+   * The synchronous primitive; {@link ManagedDocument.parse} derives from it.
+   * Absent text, empty text and text that carries no sentinel are all legal —
+   * the sentinel and regions are added by the first
+   * {@link ManagedDocument.withRegionsResult}. Only a *structurally corrupt*
+   * region layout fails, because every structural ambiguity is a case where
+   * a silent choice would destroy content a human wrote.
    */
-  readonly token: (audience?: string) => Effect.Effect<Redacted.Redacted<string>, OidcTokenError>;
+  static parseResult(source: ManagedDocumentSource): Result.Result<ManagedDocument, ManagedDocumentError>;
   /**
-   * The token's claims, decoded.
+   * Read a document out of existing text, in `Effect`.
    *
    * @remarks
-   * **The signature is deliberately not verified**, for three reasons that are
-   * recorded so nobody "fixes" it:
+   * Defined in terms of {@link ManagedDocument.parseResult} — synchronous
+   * callers can use that variant directly.
+   */
+  static readonly parse: (source: ManagedDocumentSource) => Effect.Effect<ManagedDocument, ManagedDocumentError, never>;
+  /** The HTML comment identifying this document, `<!-- namespace:key -->`. */
+  get sentinel(): string;
+  /** Does this text carry the document's sentinel? */
+  matches(text: string): boolean;
+  /** The content of one region, if the document carries it. */
+  region(key: string): Option.Option<string>;
+  /** Every region this document carries, in document order. */
+  get regions(): ReadonlyArray<{
+    readonly key: string;
+    readonly content: string;
+  }>;
+  /**
+   * The document with these regions replaced from current state.
    *
-   * 1. The token comes from the runner's own token-service endpoint over TLS.
-   *    The transport is the trust boundary, and the process asking for the
-   *    token is the process that received it.
-   * 2. The claims populate a provenance predicate, not a trust decision.
-   *    Nothing branches on them for authorization; they are recorded as
-   *    attested facts about the workflow that ran.
-   * 3. Verifying would need a JWKS fetch, which turns a decode into a network
-   *    call — untestable without a fixture server, and dependent on GitHub's
-   *    key endpoint being reachable at attestation time.
+   * @remarks
+   * The synchronous primitive; {@link ManagedDocument.withRegions} derives
+   * from it. Each entry pairs a region key with its full new content. A
+   * region already present is **replaced in place**; a region not present
+   * yet is added; regions not named are left exactly as they are; and every
+   * byte outside a managed region survives untouched. Applying entries that
+   * change nothing returns byte-identical text, which is what lets a caller
+   * compare-and-skip instead of issuing a write.
    *
-   * A consumer that needs a *verified* token needs a different operation with a
-   * different name and a different error channel, not an option on this one.
+   * Region keys share the name grammar `namespace` and `key` obey; a key
+   * outside it is a wiring error and throws at construction rather than
+   * surfacing in the typed channel.
+   */
+  withRegionsResult(entries: ReadonlyArray<readonly [key: string, content: string]>): Result.Result<ManagedDocument, ManagedDocumentError>;
+  /**
+   * The document with these regions replaced, in `Effect`.
    *
-   * Claims are on the surface rather than left to the call site because that is
-   * what makes the provenance path reachable in a test: a double built with
-   * {@link OidcTokenIssuer.layerFor} answers with real, decodable claims, where
-   * the synthetic non-JWT its predecessor returned made every consumer's
-   * `decodeJwtClaims` yield nothing and silently skipped the path under test.
+   * @remarks
+   * Defined in terms of {@link ManagedDocument.withRegionsResult} —
+   * synchronous callers can use that variant directly.
    */
-  readonly claims: (audience?: string) => Effect.Effect<OidcClaims, OidcTokenError>;
-}
-declare const OidcTokenIssuer_base: Context.ServiceClass<OidcTokenIssuer, "@effected/github-actions/OidcTokenIssuer", OidcTokenIssuerShape>;
-/**
- * The runner's OIDC token service.
- *
- * @remarks
- * Lives here rather than with attestation because it reads
- * `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL`, which
- * exist only when a workflow declares `permissions: id-token: write` — that is
- * a fact about the runner, not about signing.
- *
- * @example
- * ```ts
- * import { OidcTokenIssuer } from "@effected/github-actions";
- * import { Effect } from "effect";
- *
- * const program = Effect.gen(function* () {
- *   const issuer = yield* OidcTokenIssuer;
- *   const claims = yield* issuer.claims("sigstore");
- *   return claims.job_workflow_ref;
- * });
- * ```
- *
- * @public
- */
-declare class OidcTokenIssuer extends OidcTokenIssuer_base {
-  static readonly layer: Layer.Layer<OidcTokenIssuer, never, ActionEnvironment | HttpClient.HttpClient>;
+  withRegions(entries: ReadonlyArray<readonly [key: string, content: string]>): Effect.Effect<ManagedDocument, ManagedDocumentError>;
+  /** The marker key a region is written under: `namespace.key.region`. */
+  private wireKey;
+  /** The region key back out of a wire key, for error reporting. */
+  private regionKeyOf;
   /**
-   * An **unsigned** JWT carrying these claims.
+   * This document's own regions, in document order.
    *
    * @remarks
-   * For building test doubles, and nothing else: the signature segment is a
-   * placeholder, so this token would fail any verifier. It exists because the
-   * alternative — a double returning a synthetic non-JWT — is what made the
-   * provenance path structurally unreachable in the source package, drawing
-   * four separate apologetic comments from one consumer.
+   * A document a human already edited can be structurally corrupt, and a
+   * read has no error channel worth having — a corrupt document simply has
+   * no readable regions; {@link ManagedDocument.parseResult} is where
+   * corruption fails typed. Regions belonging to a *different* document in
+   * the same text (another namespace or key) are not this document's and are
+   * never reported.
    */
-  static readonly unsignedTokenFor: (claims: OidcClaims) => Redacted.Redacted<string>;
-  /** A test double. Unstubbed members die rather than answering with a non-token. */
-  static readonly makeTest: (overrides?: Partial<OidcTokenIssuerShape>) => OidcTokenIssuerShape;
-  /** {@link OidcTokenIssuer.makeTest} behind `Layer.succeed`. */
-  static readonly layerTest: (overrides?: Partial<OidcTokenIssuerShape>) => Layer.Layer<OidcTokenIssuer>;
+  private ownRegions;
   /**
-   * A double that answers with these claims, consistently on both members.
+   * Append the sentinel when the text does not carry it yet.
    *
    * @remarks
-   * `token()` returns a real decodable JWT built from the same claims
-   * `claims()` returns, so a consumer that decodes the token itself and a
-   * consumer that asks the service both see the same thing. A double whose two
-   * members can disagree is how a test proves a path works while production
-   * takes the other one.
+   * Appended at the end — the same position `PullRequestComment.upsert`
+   * writes its marker to — so a document rendered here and a comment written
+   * there agree about where the identity line lives.
    */
-  static readonly layerFor: (claims: OidcClaims) => Layer.Layer<OidcTokenIssuer>;
+  private ensureSentinel;
 }
 //#endregion
 //#region src/Secret.d.ts
@@ -2316,6 +3145,19 @@ declare class Secret {
    * over a `Redacted`, so a signing key has to become a string somewhere, and
    * the point of this module is that "somewhere" is here and nowhere else.
    *
+   * Signing named the member; it does not gate it. **Any in-process use that
+   * needs the raw value without writing it to a runner file is this
+   * operation** — handing a key to a library that takes a plain string. The
+   * dividing line is where the value goes, not what it is for: a value
+   * crossing into a **child's** environment is {@link Secret.forChildEnv},
+   * one written to `GITHUB_STATE` or `GITHUB_OUTPUT` is
+   * {@link Secret.forRunnerFile}, and one that stays in this process is this
+   * member. A third-party SDK that reads only the ambient environment is the
+   * hard case: this package never mutates `process.env` (reads are seeded
+   * once through `ActionEnvironment`), so if a consumer chooses that bridge,
+   * the mutation — and its restore discipline — lives in consumer code as
+   * the consumer's own tradeoff, not as a pattern this member recommends.
+   *
    * It masks even though the value is never *written* anywhere, and that is
    * deliberate rather than superstitious: a signing key that leaks does so
    * through something nobody audited — a debug log of outgoing headers, a
@@ -2463,5 +3305,5 @@ declare class ToolInstaller extends ToolInstaller_base {
   static readonly layerTest: (overrides?: Partial<ToolInstallerShape>) => Layer.Layer<ToolInstaller>;
 }
 //#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, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, GitHubToken, GitHubTokenError, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, ProcessId, type ProvisionOptions, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, WorkflowCommand, describeCause };
+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, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, 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, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, ProcessId, type ProvisionOptions, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, WorkflowCommand, describeCause, projectCheckState };
 //# sourceMappingURL=index.d.ts.map