@effected/github-actions 0.8.0 → 0.9.1

package/CheckDocument.js

@@ -29,29 +29,112 @@ var CheckReport = class extends Schema.Class("CheckReport")({
 	url: Schema.optionalKey(Schema.String)
 }) {};
 /**
-* Raised when the check document cannot be regenerated or written.
+* Raised when the check document cannot be regenerated, read back 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.
+* `read` — the sink's read-back of the live document failed; its error 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.TaggedError()("CheckDocumentError", {
-	/** Which half failed: regenerating the document, or writing it. */
-	kind: Schema.Literals(["render", "sink"]),
+	/** Which phase failed: regenerating the document, reading it back, or writing it. */
+	kind: Schema.Literals([
+		"render",
+		"read",
+		"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";
+		return this.kind === "render" ? "The check document could not be regenerated from the reported state" : this.kind === "read" ? "Reading the check document's current text failed" : "Writing the check document failed";
 	}
 };
 /**
+* A run's identity for staleness ordering: when it started and which run it
+* is.
+*
+* @remarks
+* Two delayed workflows can race for one document — a re-run's stale pass
+* must not overwrite a newer run's regions. The ordering is **total**:
+* `at` compares first (as epoch milliseconds when both sides `Date.parse`
+* cleanly, lexically otherwise), `runId` breaks ties (numerically when both
+* parse to finite numbers, lexically otherwise), and two equal stamps compare
+* as at-least-as-recent — a run may refine its own regions.
+*
+* @public
+*/
+var CheckDocumentStamp = class extends Schema.Class("CheckDocumentStamp")({
+	/** When the run started — ideally an ISO-8601 instant. */
+	at: Schema.String,
+	/** The run's identifier — on GitHub, `GITHUB_RUN_ID`. */
+	runId: Schema.String
+}) {
+	/**
+	* Is `incoming` allowed to overwrite regions stamped `existing`?
+	*
+	* @remarks
+	* Total and reflexive: equal stamps answer `true`, so a run always may
+	* rewrite what it wrote itself. Only a strictly older `incoming` answers
+	* `false`.
+	*/
+	static isAtLeastAsRecent(incoming, existing) {
+		const at = compareAt(incoming.at, existing.at);
+		if (at !== 0) return at > 0;
+		return compareRunId(incoming.runId, existing.runId) >= 0;
+	}
+};
+/** Epoch order when both sides parse as dates, lexical otherwise. */
+const compareAt = (left, right) => {
+	const leftEpoch = Date.parse(left);
+	const rightEpoch = Date.parse(right);
+	if (!Number.isNaN(leftEpoch) && !Number.isNaN(rightEpoch)) return leftEpoch === rightEpoch ? 0 : leftEpoch < rightEpoch ? -1 : 1;
+	return left === right ? 0 : left < right ? -1 : 1;
+};
+/**
+* Numeric order when both sides are non-blank finite numbers, lexical
+* otherwise.
+*
+* @remarks
+* The blank guard exists because `Number("")` and `Number("  ")` are both a
+* finite `0` — without it a blank `runId` (plausible when `GITHUB_RUN_ID` is
+* unset in a local or self-hosted run) would compare numerically equal to
+* `"0"` and outrank `"-1"`. Blank sides fall to the lexical branch, which
+* stays total and deterministic.
+*/
+const compareRunId = (left, right) => {
+	if (left.trim() !== "" && right.trim() !== "") {
+		const leftNumber = Number(left);
+		const rightNumber = Number(right);
+		if (Number.isFinite(leftNumber) && Number.isFinite(rightNumber)) return leftNumber === rightNumber ? 0 : leftNumber < rightNumber ? -1 : 1;
+	}
+	return left === right ? 0 : left < right ? -1 : 1;
+};
+/** The stamp a document's own regions carry, when they carry one. */
+const stampOf = (meta) => {
+	const at = meta.at;
+	const runId = meta.runId;
+	return at === void 0 || runId === void 0 ? void 0 : {
+		at,
+		runId
+	};
+};
+/** The most recent stamp among a document's own regions, if any carry one. */
+const maxStampOf = (regions) => {
+	let max;
+	for (const region of regions) {
+		const stamp = stampOf(region.meta);
+		if (stamp !== void 0 && (max === void 0 || CheckDocumentStamp.isAtLeastAsRecent(stamp, max))) max = stamp;
+	}
+	return max;
+};
+/**
 * 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.
@@ -121,26 +204,58 @@ var CheckDocument = class CheckDocument extends Context.Service()("@effected/git
 			const versionRef = yield* Ref.make(0);
 			const signal = yield* Latch.make(false);
 			const gate = yield* Semaphore.make(1);
+			const passTimeout = options.sinkTimeout ?? "30 seconds";
+			const sink = typeof options.sink === "function" ? { write: options.sink } : options.sink;
+			const stamp = options.stamp;
+			const stampMeta = stamp === void 0 ? void 0 : {
+				at: stamp.at,
+				runId: stamp.runId
+			};
+			const staleLoggedRef = yield* Ref.make(false);
 			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({
+				const current = sink.read === void 0 ? yield* Ref.get(writtenRef) : (yield* sink.read.pipe(Effect.timeout(passTimeout), Effect.mapError((cause) => new CheckDocumentError({
+					kind: "read",
+					cause
+				})))) ?? "";
+				const document = 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({
+				})));
+				if (stamp !== void 0) {
+					const existing = maxStampOf(document.regions);
+					if (existing !== void 0 && !CheckDocumentStamp.isAtLeastAsRecent(stamp, existing)) {
+						yield* Effect.annotateCurrentSpan("outcome", "stale");
+						yield* ((yield* Ref.getAndSet(staleLoggedRef, true)) ? Effect.logDebug : Effect.logInfo)("CheckDocument pass dropped: the document carries a more recent run's regions", {
+							incomingAt: stamp.at,
+							incomingRunId: stamp.runId,
+							existingAt: existing.at,
+							existingRunId: existing.runId
+						});
+						return "stale";
+					}
+					yield* Ref.set(staleLoggedRef, false);
+				}
+				const entries = options.render(checks);
+				const next = yield* document.withRegions(stampMeta === void 0 ? entries : entries.map(([key, content]) => [
+					key,
+					content,
+					stampMeta
+				])).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({
+				if (next.text === current) return "unchanged";
+				yield* sink.write(next.text).pipe(Effect.timeout(passTimeout), Effect.mapError((cause) => new CheckDocumentError({
 					kind: "sink",
 					cause
 				})));
 				yield* Ref.set(writtenRef, next.text);
+				return "written";
 			});
 			const flush = gate.withPermits(1)(reconcile());
 			const daemon = Effect.gen(function* () {
@@ -190,4 +305,4 @@ const unstubbed = (member) => {
 };
 
 //#endregion
-export { CheckDocument, CheckDocumentError, CheckReport };
+export { CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport };

package/ManagedDocument.js

@@ -31,10 +31,14 @@ const REGION_DIALECT = SectionDialect.make({
 * 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:
+* hand. The three 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.
+* scanner would read as a region marker, `duplicateDeclaration` refuses
+* one call that states two intentions for the same region, and
+* `invalidAttribute` refuses region metadata whose name is outside the
+* `[A-Za-z][A-Za-z0-9_-]*` grammar or whose value contains `"` or a line
+* break — either would write a marker the region scanner could not read
+* back verbatim.
 *
 * @public
 */
@@ -46,17 +50,21 @@ var ManagedDocumentError = class extends Schema.TaggedError()("ManagedDocumentEr
 		"overlappingRegions",
 		"duplicateRegion",
 		"markerInContent",
-		"duplicateDeclaration"
+		"duplicateDeclaration",
+		"invalidAttribute"
 	]),
 	/** 1-based line of the offending marker, for the structural kinds. */
 	line: Schema.optionalKey(Schema.Number),
 	/** The region key involved, when the failure names one. */
-	key: Schema.optionalKey(Schema.String)
+	key: Schema.optionalKey(Schema.String),
+	/** The offending metadata attribute's name, for `invalidAttribute`. */
+	attribute: Schema.optionalKey(Schema.String)
 }) {
 	get message() {
 		const which = this.key === void 0 ? "" : ` for region "${this.key}"`;
+		const named = this.attribute === void 0 ? "" : ` (attribute "${this.attribute}")`;
 		const where = this.line === void 0 ? "" : ` at line ${this.line}`;
-		return `${KIND_PROSE[this.kind]}${which}${where}`;
+		return `${KIND_PROSE[this.kind]}${which}${named}${where}`;
 	}
 };
 const KIND_PROSE = {
@@ -65,7 +73,8 @@ const KIND_PROSE = {
 	overlappingRegions: "Managed region opens inside another",
 	duplicateRegion: "Managed region appears twice",
 	markerInContent: "Region content contains a managed-region marker",
-	duplicateDeclaration: "Region was declared twice in one call"
+	duplicateDeclaration: "Region was declared twice in one call",
+	invalidAttribute: "Region metadata has an invalid attribute name or value"
 };
 /** Map a templates scan failure onto this surface's vocabulary. */
 const STRUCTURAL_KIND = {
@@ -173,7 +182,29 @@ var ManagedDocument = class ManagedDocument extends Schema.Class("ManagedDocumen
 		const found = this.ownRegions().find((entry) => entry.key === key);
 		return found === void 0 ? Option.none() : Option.some(found.content);
 	}
-	/** Every region this document carries, in document order. */
+	/**
+	* One region's content and metadata together, if the document carries it.
+	*
+	* @remarks
+	* `meta` is the region's `name="value"` marker attributes, empty when the
+	* marker carries none. Metadata never participates in region
+	* addressability — this looks up by key exactly as
+	* {@link ManagedDocument.region} does.
+	*/
+	entry(key) {
+		const found = this.ownRegions().find((candidate) => candidate.key === key);
+		return found === void 0 ? Option.none() : Option.some({
+			content: found.content,
+			meta: found.meta
+		});
+	}
+	/**
+	* Every region this document carries, in document order.
+	*
+	* @remarks
+	* `meta` is always present: a region whose marker carries no attributes
+	* reports an empty record, so callers never branch on absence.
+	*/
 	get regions() {
 		return this.ownRegions();
 	}
@@ -182,12 +213,22 @@ var ManagedDocument = class ManagedDocument extends Schema.Class("ManagedDocumen
 	*
 	* @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.
+	* from it. Each entry pairs a region key with its full new content, plus
+	* optional metadata. 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.
+	*
+	* `meta` becomes `name="value"` attributes on the region's BEGIN marker.
+	* It round-trips verbatim through {@link ManagedDocument.entry}, survives
+	* writes by parties that do not know about it — a region not named in a
+	* call keeps its content *and* its metadata untouched — and never
+	* participates in region addressability: a region is found by key alone,
+	* so changing metadata updates the region in place. A two-element entry
+	* behaves exactly as it always has. Names must match
+	* `[A-Za-z][A-Za-z0-9_-]*` and values may not contain `"` or a line
+	* break; violations fail typed as `invalidAttribute`.
 	*
 	* Region keys share the name grammar `namespace` and `key` obey; a key
 	* outside it is a wiring error and throws at construction rather than
@@ -203,17 +244,18 @@ var ManagedDocument = class ManagedDocument extends Schema.Class("ManagedDocumen
 				...failure.key === void 0 ? {} : { key: failure.key }
 			}));
 		}
-		const declared = entries.map(([key, content]) => SectionId.make({
+		const declared = entries.map(([key, content, meta]) => SectionId.make({
 			key: this.wireKey(key),
 			commentStyle: CommentStyle.html
-		}).section(content));
+		}).section(content, meta));
 		const reconciled = parsed.success.reconcile(declared);
 		if (Result.isFailure(reconciled)) {
 			const failure = reconciled.failure;
 			if (failure.reason === "unknownCommentStyle") throw new Error("ManagedDocument: the region dialect rejected its own comment style");
 			return Result.fail(new ManagedDocumentError({
 				kind: failure.reason,
-				key: this.regionKeyOf(failure.key)
+				key: this.regionKeyOf(failure.key),
+				...failure.attribute === void 0 ? {} : { attribute: failure.attribute }
 			}));
 		}
 		const withSentinel = this.ensureSentinel(reconciled.success.text, parsed.success.eol);
@@ -259,7 +301,8 @@ var ManagedDocument = class ManagedDocument extends Schema.Class("ManagedDocumen
 		const prefix = `${this.namespace}.${this.key}.`;
 		return parsed.success.sections.filter((placed) => placed.section.key.startsWith(prefix)).map((placed) => ({
 			key: placed.section.key.slice(prefix.length),
-			content: placed.section.content
+			content: placed.section.content,
+			meta: placed.section.attributes
 		}));
 	}
 	/**

package/README.md

@@ -193,12 +193,40 @@ 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;
+  return yield* doc.flush;
 });
-// one write carrying the final state; a render byte-identical to the last one writes nothing
+// "written"   — one write carrying the final state
+// "unchanged" — the render was byte-identical to the last one, so nothing was sent
+// "stale"     — a newer run owns the document; this pass was dropped (see below)
 ```
 
-The debounce is trailing with a max-wait, so a burst of reports coalesces into one write carrying the *final* state while a steady stream still surfaces progress. `CheckState` is the vocabulary both of them speak, and it is deliberately wider than GitHub's conclusion set — `running` is a state rather than the absence of one, and `user_interaction_required` names a pipeline waiting on a human. `projectCheckState` maps each onto the wire form GitHub wants, as a status plus a conclusion exactly when the status is `completed`.
+The debounce is trailing with a max-wait, so a burst of reports coalesces into one write carrying the *final* state while a steady stream still surfaces progress.
+
+A region can also carry metadata: `withRegions` takes `[key, content, meta]` triples, the pairs ride the region's own marker, and `entry(key)` reads them back verbatim. Metadata survives a writer that knows nothing about it — a region a call does not name keeps its content *and* its metadata — and never takes part in addressing a region, so changing it updates that region in place rather than growing a second one.
+
+`CheckDocument` uses exactly that to survive two runs writing one document — a re-run overlapping the delayed run it replaced. Give the layer this run's `stamp` and a sink that can `read` as well as `write`, and each pass reconciles against the live document instead of a private shadow of what this process last wrote:
+
+```ts
+import { CheckDocument } from "@effected/github-actions";
+import type { Effect } from "effect";
+
+declare const startedAt: string;
+declare const runId: string;
+declare const readComment: Effect.Effect<string | undefined>;
+declare const writeComment: (text: string) => Effect.Effect<void>;
+
+const layer = CheckDocument.layer({
+  namespace: "release-bot",
+  key: "checks",
+  render: (checks) => [...checks].map(([name, report]) => [name, report.state] as const),
+  sink: { write: writeComment, read: readComment },
+  stamp: { at: startedAt, runId }, // a per-run constant — mint it once at startup
+});
+```
+
+Every region the run writes then carries its `at` and `runId`, and a pass whose stamp is strictly older than the newest stamp already on the document is dropped rather than written — `flush` answers `"stale"` and the reconciler logs the drop once, at the transition. Equal stamps pass, so a run always may refine its own regions. Keeping the stamp constant is what preserves write suppression: the same run rendering the same state still produces byte-identical text.
+
+`CheckState` is the vocabulary both of them speak, and it is deliberately wider than GitHub's conclusion set — `running` is a state rather than the absence of one, and `user_interaction_required` names a pipeline waiting on a human. `projectCheckState` maps each onto the wire form GitHub wants, as a status plus a conclusion exactly when the status is `completed`.
 
 ## Testing
 
@@ -239,9 +267,9 @@ const TestOutputs = ActionOutputs.layerTest({
 - `OidcTokenIssuer` — the runner's OIDC token service, with unverified claim decoding for provenance predicates.
 - `ActionsIdentityToken` / `ActionsProvenance` — the `@effected/sbom` seam: `layer` serves that package's `IdentityToken` contract from the runner's issuer, and `capture` builds a `SlsaProvenance` predicate out of the runner's OIDC claims.
 - `GitHubMarkdown` — the escaping-safe writer for GitHub surfaces: `table`, `tableFor(schema)`, `heading`, `link`, `code`, `codeBlock`, `list`, `details` and `raw`, and the package's only importer of `@effected/markdown`.
-- `ManagedDocument` — marker-delimited named regions in text a human also edits, for a sticky comment or a managed pull request description; content outside the regions survives byte-for-byte.
+- `ManagedDocument` — marker-delimited named regions in text a human also edits, for a sticky comment or a managed pull request description; content outside the regions survives byte-for-byte, and each region can carry marker metadata that round-trips through `entry(key)` without ever addressing the region.
 - `CheckState` / `projectCheckState` — the kit's check vocabulary, wider than GitHub's conclusions, and its projection onto the check-run wire form.
-- `CheckDocument` — the debounced check-to-document reconciler: report states as they change, and one write lands carrying the final one.
+- `CheckDocument` — the debounced check-to-document reconciler: report states as they change, and one write lands carrying the final one. `stamp` plus a readable sink lets two runs share one document, dropping a strictly older run's pass instead of clobbering the newer one; `flush` reports `written`, `unchanged` or `stale`.
 - `ToolInstaller` — download, extract and cache a toolchain in the runner's tool cache, with no `@actions/tool-cache` dependency.
 - `BlobStore` — durable `get`/`put`/`has` over bytes plus a metadata channel, backed by `layerS3` (SigV4-signed, no `@aws-sdk/*` dependency) or `GitHubCacheBlobStore.layer` (the runner's own cache); `layerMemory` runs the real envelope framing for tests.
 

package/index.d.ts

@@ -2412,41 +2412,108 @@ declare const CheckReport_base: Schema.Class<CheckReport, Schema.Struct<{
  */
 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"]>;
+  /** Which phase failed: regenerating the document, reading it back, or writing it. */
+  readonly kind: Schema.Literals<readonly ["render", "read", "sink"]>;
   /** The underlying failure. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Raised when the check document cannot be regenerated or written.
+ * Raised when the check document cannot be regenerated, read back 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.
+ * `read` — the sink's read-back of the live document failed; its error 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 CheckDocumentError extends CheckDocumentError_base {
   get message(): string;
 }
+declare const CheckDocumentStamp_base: Schema.Class<CheckDocumentStamp, Schema.Struct<{
+  /** When the run started — ideally an ISO-8601 instant. */
+  readonly at: Schema.String;
+  /** The run's identifier — on GitHub, `GITHUB_RUN_ID`. */
+  readonly runId: Schema.String;
+}>, {}>;
+/**
+ * A run's identity for staleness ordering: when it started and which run it
+ * is.
+ *
+ * @remarks
+ * Two delayed workflows can race for one document — a re-run's stale pass
+ * must not overwrite a newer run's regions. The ordering is **total**:
+ * `at` compares first (as epoch milliseconds when both sides `Date.parse`
+ * cleanly, lexically otherwise), `runId` breaks ties (numerically when both
+ * parse to finite numbers, lexically otherwise), and two equal stamps compare
+ * as at-least-as-recent — a run may refine its own regions.
+ *
+ * @public
+ */
+declare class CheckDocumentStamp extends CheckDocumentStamp_base {
+  /**
+   * Is `incoming` allowed to overwrite regions stamped `existing`?
+   *
+   * @remarks
+   * Total and reflexive: equal stamps answer `true`, so a run always may
+   * rewrite what it wrote itself. Only a strictly older `incoming` answers
+   * `false`.
+   */
+  static isAtLeastAsRecent(incoming: {
+    readonly at: string;
+    readonly runId: string;
+  }, existing: {
+    readonly at: string;
+    readonly runId: string;
+  }): boolean;
+}
+/**
+ * What one reconcile pass did.
+ *
+ * @remarks
+ * `written` — the render changed and the sink wrote it. `unchanged` — the
+ * render was byte-identical, so no write was issued. `stale` — the document
+ * already carries regions from a more recent run, so the pass was dropped
+ * without writing (only possible when {@link CheckDocumentOptions.stamp} is
+ * set). A plain literal union: callers that ignored `flush`'s old `void`
+ * success stay compile-compatible.
+ *
+ * @public
+ */
+type CheckFlushOutcome = "written" | "unchanged" | "stale";
 /**
  * How a rendered document leaves the process: the narrow sink contract.
  *
  * @remarks
- * 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 function form is 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
+ * write's success value is ignored; a failure surfaces as
+ * {@link CheckDocumentError} with `kind: "sink"`. Provide any services the
+ * effects need when constructing the sink — the reconciler runs them as
+ * given.
+ *
+ * The object form adds an optional `read`: the live document's current text,
+ * fetched at the start of every pass and used as the base to reconcile
+ * against instead of the last text this process wrote. `undefined` means
+ * "nothing there yet" — a fresh document. That is what lets two runs share
+ * one document: each pass sees what the *other* run wrote, not a private
+ * shadow. A failed read surfaces as `kind: "read"`. A bare function is
+ * exactly `{ write }`.
  *
  * @public
  */
-type CheckDocumentSink = (rendered: string) => Effect.Effect<unknown, unknown>;
+type CheckDocumentSink = ((rendered: string) => Effect.Effect<unknown, unknown>) | {
+  /** Write one rendered document. */
+  readonly write: (rendered: string) => Effect.Effect<unknown, unknown>;
+  /** The live document's current text, or `undefined` for none yet. */
+  readonly read?: Effect.Effect<string | undefined, unknown> | undefined;
+};
 /**
  * Options for {@link CheckDocument.layer}.
  *
@@ -2477,6 +2544,27 @@ interface CheckDocumentOptions {
   readonly render: (checks: ReadonlyMap<string, CheckReport>) => ReadonlyArray<readonly [key: string, content: string]>;
   /** Where the rendered document goes. */
   readonly sink: CheckDocumentSink;
+  /**
+   * This run's identity, for staleness ordering against other runs.
+   *
+   * @remarks
+   * A **per-run constant** — mint it once at startup, never per pass. When
+   * present, every region a pass writes carries `at`/`runId` metadata, and a
+   * pass whose stamp is strictly older than the most recent stamp already on
+   * the document is **dropped** rather than written, so a delayed re-run can
+   * never clobber a newer run's regions. Equal stamps pass: a run may refine
+   * its own regions.
+   *
+   * The constant is what preserves write suppression: the same run rendering
+   * the same state produces byte-identical text (stamp included), so no
+   * write is issued. The accepted corner is that a content-identical pass
+   * therefore does not refresh the document's stamp to "now" — suppression
+   * wins — which is sound because only strictly-older stamps drop.
+   */
+  readonly stamp?: {
+    readonly at: string;
+    readonly runId: string;
+  } | undefined;
   /**
    * Debounce parameters: `quiet` is the trailing settle window, `maxWait`
    * the staleness bound under a steady stream of reports. Defaults: 500
@@ -2487,8 +2575,9 @@ interface CheckDocumentOptions {
     readonly maxWait?: Duration.Input | undefined;
   } | undefined;
   /**
-   * How long one sink write may run before the pass fails with
-   * `kind: "sink"`. Default: 30 seconds.
+   * How long one sink write — or one read-back, when the sink carries a
+   * `read` — may run before the pass fails with `kind: "sink"` (or
+   * `kind: "read"`). Default: 30 seconds.
    *
    * @remarks
    * The reconciler serializes passes behind one permit, and the finalizer's
@@ -2524,9 +2613,11 @@ interface CheckDocumentShape {
    * @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.
+   * even when the scope closes inside the quiet window. The outcome says
+   * what the pass did — `written`, `unchanged` or `stale` — and callers
+   * that ignore it stay exactly as they were.
    */
-  readonly flush: Effect.Effect<void, CheckDocumentError>;
+  readonly flush: Effect.Effect<CheckFlushOutcome, CheckDocumentError>;
 }
 declare const CheckDocument_base: Context.ServiceClass<CheckDocument, "@effected/github-actions/CheckDocument", CheckDocumentShape>;
 /**
@@ -3610,11 +3701,13 @@ declare class GitHubToken {
 //#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"]>;
+  readonly kind: Schema.Literals<readonly ["unterminatedRegion", "orphanedEnd", "overlappingRegions", "duplicateRegion", "markerInContent", "duplicateDeclaration", "invalidAttribute"]>;
   /** 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>;
+  /** The offending metadata attribute's name, for `invalidAttribute`. */
+  readonly attribute: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Raised when a managed document cannot be read or regenerated without
@@ -3624,10 +3717,14 @@ declare const ManagedDocumentError_base: Schema.Class<ManagedDocumentError, Sche
  * 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:
+ * hand. The three 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.
+ * scanner would read as a region marker, `duplicateDeclaration` refuses
+ * one call that states two intentions for the same region, and
+ * `invalidAttribute` refuses region metadata whose name is outside the
+ * `[A-Za-z][A-Za-z0-9_-]*` grammar or whose value contains `"` or a line
+ * break — either would write a marker the region scanner could not read
+ * back verbatim.
  *
  * @public
  */
@@ -3729,28 +3826,58 @@ declare class ManagedDocument extends ManagedDocument_base {
   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. */
+  /**
+   * One region's content and metadata together, if the document carries it.
+   *
+   * @remarks
+   * `meta` is the region's `name="value"` marker attributes, empty when the
+   * marker carries none. Metadata never participates in region
+   * addressability — this looks up by key exactly as
+   * {@link ManagedDocument.region} does.
+   */
+  entry(key: string): Option.Option<{
+    readonly content: string;
+    readonly meta: Readonly<Record<string, string>>;
+  }>;
+  /**
+   * Every region this document carries, in document order.
+   *
+   * @remarks
+   * `meta` is always present: a region whose marker carries no attributes
+   * reports an empty record, so callers never branch on absence.
+   */
   get regions(): ReadonlyArray<{
     readonly key: string;
     readonly content: string;
+    readonly meta: Readonly<Record<string, string>>;
   }>;
   /**
    * The document with these regions replaced from current state.
    *
    * @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.
+   * from it. Each entry pairs a region key with its full new content, plus
+   * optional metadata. 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.
+   *
+   * `meta` becomes `name="value"` attributes on the region's BEGIN marker.
+   * It round-trips verbatim through {@link ManagedDocument.entry}, survives
+   * writes by parties that do not know about it — a region not named in a
+   * call keeps its content *and* its metadata untouched — and never
+   * participates in region addressability: a region is found by key alone,
+   * so changing metadata updates the region in place. A two-element entry
+   * behaves exactly as it always has. Names must match
+   * `[A-Za-z][A-Za-z0-9_-]*` and values may not contain `"` or a line
+   * break; violations fail typed as `invalidAttribute`.
    *
    * 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>;
+  withRegionsResult(entries: ReadonlyArray<readonly [key: string, content: string, meta?: Readonly<Record<string, string>>]>): Result.Result<ManagedDocument, ManagedDocumentError>;
   /**
    * The document with these regions replaced, in `Effect`.
    *
@@ -3758,7 +3885,7 @@ declare class ManagedDocument extends ManagedDocument_base {
    * Defined in terms of {@link ManagedDocument.withRegionsResult} —
    * synchronous callers can use that variant directly.
    */
-  withRegions(entries: ReadonlyArray<readonly [key: string, content: string]>): Effect.Effect<ManagedDocument, ManagedDocumentError>;
+  withRegions(entries: ReadonlyArray<readonly [key: string, content: string, meta?: Readonly<Record<string, 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. */
@@ -4413,5 +4540,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 DetachedProcessOps, 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 };
+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, CheckDocumentStamp, type CheckFlushOutcome, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, ChildEnv, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedProcessOps, 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/index.js

@@ -18,7 +18,7 @@ import { GitHubCacheBlobStore } from "./BlobStore.githubCache.js";
 import { CacheKey, CacheKeyError } from "./CacheKey.js";
 import { CheckState, projectCheckState } from "./CheckState.js";
 import { ManagedDocument, ManagedDocumentError } from "./ManagedDocument.js";
-import { CheckDocument, CheckDocumentError, CheckReport } from "./CheckDocument.js";
+import { CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport } from "./CheckDocument.js";
 import { ChildEnv } from "./ChildEnv.js";
 import { DetachedProcess, DetachedProcessError, ProcessId } from "./DetachedProcess.js";
 import { DryRun } from "./DryRun.js";
@@ -27,4 +27,4 @@ import { GitHubToken, GitHubTokenError } from "./GitHubToken.js";
 import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
 import { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError } from "./PackageManagerInstaller.js";
 
-export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputError, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckReport, CheckState, ChildEnv, DetachedProcess, DetachedProcessError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, OidcClaims, OidcTokenError, OidcTokenIssuer, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RunnerContext, Secret, ToolInstaller, ToolInstallerError, WorkflowCommand, describeCause, projectCheckState };
+export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputError, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedProcess, DetachedProcessError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, OidcClaims, OidcTokenError, OidcTokenIssuer, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RunnerContext, Secret, ToolInstaller, ToolInstallerError, WorkflowCommand, describeCause, projectCheckState };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github-actions",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"private": false,
 	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
 	"keywords": [
@@ -39,12 +39,12 @@
 	},
 	"dependencies": {
 		"@azure/storage-blob": "^12.33.0",
-		"@effected/github": "^0.5.0",
+		"@effected/github": "^0.7.0",
 		"@effected/glob": "^0.4.0",
 		"@effected/markdown": "^0.6.0",
-		"@effected/npm": "^0.10.0",
-		"@effected/sbom": "^0.4.0",
-		"@effected/templates": "^0.3.0"
+		"@effected/npm": "^0.11.0",
+		"@effected/sbom": "^0.4.1",
+		"@effected/templates": "^0.4.0"
 	},
 	"peerDependencies": {
 		"@effect/platform-node": "4.0.0-rc.109",