🔀 Create or bring up to date one pull request for the published branch

`<PullRequest>` is an upsert over one explicit pull-request identity. Without a
number it asks for a pull request from this head to this base — creating one, or
adopting the compatible one an interrupted attempt already made. With a number
it asks for that exact pull request, and brings its title, body, draft state and
base to what the invocation says; when they already say it, the no-op is
recorded as the shared adoption rather than as an action of its own.

The two modes are two resources, so they are two natural-key shapes — a create
key of Repository plus branch pair, an update key of Repository plus number —
while the complete fingerprint still covers every input, `number` included. The
shared state machine is untouched: an update that has work to do is the
requested completion being absent, with the existing pull request retained as
the pre-state a performed update describes itself against. A performed update
whose pre-state already agreed with every requested field is refused, because
that record describes work with nothing to do.

It never pushes. The run must already hold its own successful `<Git.Push>`
result for this exact Repository identity, head branch, destination ref and
commit, before a creation and before an update alike, and the head is never
rewritten.

Updates are one REST field change plus, when draft state differs, one GraphQL
draft transition, each issued at most once and followed by exactly one
observation that decides the outcome. A rejected mutation, a partial multi-call
update and an unreadable answer are unavailability: nothing repeats inside the
attempt, and a later attempt finishes only what is left.

Every payload the adapter takes in — a listing candidate, a numbered lookup, a
creation's answer, an update's final observation — goes through one reading that
carries the eleven snapshot facts plus the repositories the head and base live
in. Nothing is counted before it is read, so a listing of members this adapter
cannot understand is unavailability rather than an ambiguity or a conflict; a
numbered answer becomes a closed conflict only once it has proven it is this
pull request; a fork candidate is outside the supported direct same-repository
key and is excluded before anything is counted; and a creation naming another
repository publishes no completion. Repository names compare without case.

Two defects the review reproduced earlier are closed. The Push admission
required only a matching natural key, so a record whose internally valid inputs
and result named another repository and branch authorized this one; it now
requires the key, the inputs, the parsed record and the request to describe one
publication. And a page walk that could not be completed — an off-origin,
malformed or otherwise unfollowable next relation — reported the candidates it
had collected; it is now unavailability, which is never absence.

The first adapter works over github.com, selected from the private retained
locator and credentialed from GH_TOKEN then GITHUB_TOKEN. The locator, the
endpoint, the credential and every raw response stay in the per-invocation
provider closure; routing middleware sees the frozen JSON request and the
journal holds the normalized record alone.

Author: taras

architecture.md

@@ -989,7 +989,7 @@ absence and refuses conflicting or permanently ambiguous state. Temporary
 provider unavailability may be retried or suspended by explicit middleware; it
 never authorizes a duplicate effect while completion is unknown.
 
-Git-host mutations — Git push, pull-request creation and issue creation — share
+Git-host mutations — Git push, pull-request upsert and issue creation — share
 one provider-neutral reconciliation of that boundary, so a new Git-host effect
 kind supplies a request and a provider rather than a replay policy of its own.
 Prompt is not one of them: it keeps its own Agent-provider contract. A live
@@ -2306,7 +2306,7 @@ Status is measured against main.
 | caller-owned storage transaction | publishes several changes, including journal events, in one transaction nothing else enlists in | built on main |
 | live durable-operation coordinator | explicitly coordinates structured live execution with existing Yield publication while leaving replay and callback effects unchanged | built on the #365 stack |
 | Workspace coordination API | fails closed by default; replaceable context routes only a one-use provider selection, while the selected provider directly invokes an execution-owned credentialed capability for execution, publication and failure activation | built on the #365 stack; the Deno provider installs an adapter-private atomic handler |
-| shared Git-host reconciliation | reconciles Git push, pull-request creation and issue creation through one provider-neutral state machine journaled as `git_host_effect` — Prompt is not a consumer and keeps its own Agent-provider contract: run and expansion identity derived by the engine, observation before mutation, adoption of a proven compatible completion, one performance of a proven absence, refusal of conflict and permanent ambiguity, temporary unavailability as its own ordinary failure, and a provider free to support only some kinds; routing is one request-only contextual operation carrying no completion authority, and only an answer the invocation's own terminal accepted can author a journaled outcome | built on the #297 stack; `Git.Push` is its first consumer, built on the #370 stack, while pull request and issue components remain unbuilt (#295, #296) |
+| shared Git-host reconciliation | reconciles Git push, pull-request upsert and issue creation through one provider-neutral state machine journaled as `git_host_effect` — Prompt is not a consumer and keeps its own Agent-provider contract: run and expansion identity derived by the engine, observation before mutation, adoption of a proven compatible completion, one performance of a proven absence, refusal of conflict and permanent ambiguity, temporary unavailability as its own ordinary failure, and a provider free to support only some kinds; routing is one request-only contextual operation carrying no completion authority, and only an answer the invocation's own terminal accepted can author a journaled outcome | built on the #297 stack; `Git.Push` is its first consumer, built on the #370 stack, and `<PullRequest>` its second — a create-or-update upsert — built on the #295 stack, while the issue component remains unbuilt (#296) |
 | explicit WorkflowRun journal route | binds one already-filtered publication to one exact active transaction and otherwise uses ordinary serialized journal storage | built on the #365 stack |
 | `API.Service` / `startService()` | creates an authenticated, supervised loopback service attachment through a provider-neutral operation | built on main |
 | foreground command routing and retention | forwards a child's channels live, captures stdout for a `<Capture as>` region, and retains output only when the host asked for a record | built on the #441 stack |
@@ -2324,6 +2324,7 @@ Status is measured against main.
 | `<Repository>` / `<Worktree>` / `<Dir>` composition | names a Git repository and its linked checkouts inside the run-owned Workspace, installs each as contextual working directory, and retains creation identity beside the retained Git bytes | built on the #293 stack, Deno provider only |
 | transactional Git effects (`Git.Switch` / `Git.Add` / `Git.Commit`) | publish local Git mutations with their journal result; the enclosing Repository and the contextual working directory select which retained checkout one runs in, and neither observation carries authority — the observed record is compared with the retained row and the directory with the checkouts that row holds, so a failure of authority, of retained state or of an unrecognized native condition fails the run instead of publishing a result | built on the #294 stack, Deno provider only |
 | `Git.Push` | publishes the selected checkout's exact current named branch and commit to the same branch on the retained Repository's canonical `origin`, reconciled through the shared Git-host state machine rather than through a Workspace transaction: no props and no component result, no force, no upstream mutation and no implicit staging or committing; the durable request and record carry the Repository's filtered identity without its checkout path, and the transport runs in a provider-owned isolated control repository reading the checkout's objects through an object-source attachment whose alternates chain and object tree are proven contained before the first remote observation, aimed at the exact private retained locator | built on the #370 stack, Deno provider only |
+| `<PullRequest>` | upserts one pull request of the selected checkout's current named branch, reconciled through the shared Git-host state machine: a required `title`, an optional positive-integer `number`, an optional `base` defaulting to the Repository's retained initial branch, an optional `draft`, and the rendered content as the body; it renders nothing and returns stable evidence through `as` — the filtered Repository identity, the provider's own stable pull-request identity, number, URL, open state, and the head and base SHAs of the snapshot it finished at. Without a number it creates one pull request for the head/base pair or adopts the compatible one an interrupted attempt left; with a number it brings that exact pull request's title, body, draft state and base to what the request says, records a no-op when they already match, and refuses a number belonging to another repository, opened from another head, or no longer open. It never pushes, never rewrites a head, and never reopens, merges or comments. The run must already hold its own successful `Git.Push` result for that exact Repository identity, head branch, destination ref and commit — proven by a scan that requires the record's natural key, inputs and result to describe one publication — and a missing, conflicting or unreadable one fails locally before the Git host is observed; the first adapter works over `github.com` on REST plus the two GraphQL draft transitions, selected from the private retained locator, credentialed from `GH_TOKEN` then `GITHUB_TOKEN`, issuing each required mutation at most once per attempt and deciding the outcome by one observation, with the locator, endpoint, credential and payload confined to the per-invocation provider closure | built on the #295 stack, Deno provider only |
 | workflow lifecycle inspection and control | reads status/list/history without advancing a run, enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | built on the #367 stack |
 | historical authored source | retains an authored durable operation's normalized `SourcePosition` beside its identity, and history parses it or refuses the entry | built on the #367 stack |
 | history fork | creates a new run from one compatible checkpoint and retained Workspace root | defined in `specs/workflow-workspace-spec.md`, unbuilt (#368) |

packages/workflow/mod.ts

@@ -73,6 +73,7 @@ export {
   GitCompositionProviderError,
   GitOperationError,
   GitOperationProtocolError,
+  PullRequestAuthorityError,
   RepositoryCompositionError,
   RepositoryCompositionProtocolError,
   RepositoryCompositionProviderError,
@@ -81,6 +82,7 @@ export {
 } from "./src/composition/errors.ts";
 export type {
   GitFailureReason,
+  PullRequestAuthorityReason,
   RepositoryFailureReason,
   WorktreeFailureReason,
 } from "./src/composition/errors.ts";
@@ -159,6 +161,45 @@ export type {
   GitPushRequest,
   GitPushResult,
 } from "./src/composition/git-push-records.ts";
+export {
+  OPEN,
+  parsePullRequestInputs,
+  parsePullRequestNaturalKey,
+  parsePullRequestObservations,
+  parsePullRequestPreState,
+  parsePullRequestRecord,
+  parsePullRequestResult,
+  parsePullRequestSnapshot,
+  PULL_REQUEST,
+  pullRequestAgrees,
+  pullRequestMode,
+  pullRequestInputsJson,
+  pullRequestNaturalKey,
+  pullRequestNaturalKeyJson,
+  pullRequestNumber,
+  pullRequestObservationsJson,
+  pullRequestPreStateJson,
+  pullRequestResultJson,
+  pullRequestResultOf,
+  pullRequestSnapshotJson,
+  sameNaturalKey,
+  samePullRequestIdentity,
+} from "./src/composition/pull-request-records.ts";
+export type {
+  PullRequestCreateKey,
+  PullRequestExpectation,
+  PullRequestInputs,
+  PullRequestMode,
+  PullRequestNaturalKey,
+  PullRequestObservations,
+  PullRequestOutcome,
+  PullRequestPreState,
+  PullRequestRequest,
+  PullRequestResult,
+  PullRequestSnapshot,
+  PullRequestUpdateKey,
+} from "./src/composition/pull-request-records.ts";
+export { admitPushEvidence } from "./src/composition/push-evidence.ts";
 export { useCompositionComponents } from "./src/composition/installation.ts";
 
 export { GIT_HOST_API, GitHost } from "./src/git-host/api.ts";

packages/workflow/src/composition/components/PullRequest.ts

@@ -0,0 +1,175 @@
+/**
+ * `<PullRequest>` — one pull request for the branch this run published, created
+ * or brought up to date (specs/workflow-workspace-spec.md §7.5).
+ *
+ * ```md
+ * <Repository name="project" url={props.repository}>
+ *   <Git.Switch branch="release/1.4" />
+ *   <Git.Add paths="release/notes.md" />
+ *   <Git.Commit message="Prepare 1.4" as="commit" />
+ *   <Git.Push />
+ *   <PullRequest number={props.pullRequestNumber} title="Prepare 1.4" as="pullRequest">
+ *     Prepared from commit {commit}.
+ *   </PullRequest>
+ * </Repository>
+ * ```
+ *
+ * `title` is required, `number` defaults to none, `base` defaults to the
+ * Repository's recorded initial branch, `draft` defaults to false, and the
+ * rendered content is the body. The head is the branch the selected checkout is
+ * on — decided the way §7.1 decides every Git operation's place, by the
+ * enclosing `<Repository>` and the contextual working directory — so there is no
+ * `head`, `repository`, `remote` or `provider` prop to say it a second way.
+ *
+ * ## An upsert over one explicit identity
+ *
+ * Without a number the document is asking for *a pull request from this head to
+ * this base*: one is created, or the compatible one an interrupted earlier
+ * attempt already created is adopted. With a number it is asking for *that pull
+ * request*: its title, body, draft state and base are brought to what this
+ * invocation says, and if they already say it, nothing is performed and the
+ * no-op is recorded.
+ *
+ * Which of the two it is, is the document's own word rather than a search. A
+ * number that names a pull request belonging to another Repository, opened from
+ * another head, or no longer open is a conflict — never a rewrite onto
+ * unrelated state. The head is never rewritten either: an update moves the four
+ * fields it names and nothing else.
+ *
+ * ## It publishes nothing
+ *
+ * A pull request is a statement about a branch that already exists on the Git
+ * host, and this component never makes one exist. `<Git.Push />` is written
+ * explicitly, and the run must already hold that Push's own successful result
+ * for this exact Repository, head branch, destination ref and commit — before a
+ * creation and before an update alike. Direct remote observation is not a
+ * substitute: a branch this run finds at the host may have been put there by
+ * anything, and opening or repointing a pull request for it would be publishing
+ * somebody else's work under this run's name.
+ *
+ * ## What it produces
+ *
+ * Stable evidence of what this effect settled on, bound through `as`: the
+ * filtered Repository identity, the provider's own stable identity for the pull
+ * request, its number, its URL, its open state, and the head and base commits
+ * of the snapshot the reconciliation finished at. Reviews, comments, checks,
+ * labels, merge state and later edits are separate reads rather than freshness
+ * smuggled into the result — a replayed run hands back exactly what the run
+ * recorded, whatever the pull request looks like now.
+ *
+ * ## Failure
+ *
+ * Content expands first and completely, so a body that failed to render stops
+ * everything this component owns before a Repository is even observed. After
+ * that, a missing Repository context, a checkout whose HEAD names no branch and
+ * missing, conflicting or unreadable Push evidence are all decided locally,
+ * before the Git host exists in the story, and each fails the run rather than
+ * printing: a later sibling must not run as though a pull request had been
+ * opened. What the Git host itself answers — a conflict, an ambiguity, an
+ * unavailability — travels under §10.2's shared vocabulary.
+ */
+
+import { cwd } from "@executablemd/runtime";
+import { content, hasContent } from "@executablemd/core";
+import type { PropsSchema, ReturnsSchema } from "@executablemd/core";
+import type { Operation } from "effection";
+import type { Json } from "@executablemd/durable-streams";
+import { GitComposition } from "../git-api.ts";
+import { currentRepository } from "../context.ts";
+import { PullRequestAuthorityError } from "../errors.ts";
+import { pullRequestResultJson } from "../pull-request-records.ts";
+
+/** The component name, as a document writes it and as a refusal names it. */
+export const PULL_REQUEST_ELEMENT = "<PullRequest>";
+
+export const props: PropsSchema = {
+  type: "object",
+  properties: {
+    /** The pull request to bring up to date. Absent asks for one to exist. */
+    number: { type: "integer", minimum: 1 },
+    title: { type: "string", minLength: 1 },
+    base: { type: "string", minLength: 1 },
+    draft: { type: "boolean", default: false },
+  },
+  required: ["title"],
+  additionalProperties: false,
+};
+
+/**
+ * The evidence a document binds, exactly.
+ *
+ * Closed, because this is the boundary a document reads the record through: a
+ * member arriving here that the contract does not declare would be a provider
+ * detail reaching a binding, and a missing one would be a document reading
+ * `undefined` where a number was promised.
+ */
+export const returns: ReturnsSchema = {
+  type: "object",
+  properties: {
+    repository: {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        locatorFingerprint: { type: "string", pattern: "^[0-9a-f]{64}$" },
+        requestedBase: { type: ["string", "null"] },
+        creationCommit: { type: "string", pattern: "^([0-9a-f]{40}|[0-9a-f]{64})$" },
+        primaryBranch: { type: "string", minLength: 1 },
+        objectFormat: { enum: ["sha1", "sha256"] },
+      },
+      required: [
+        "name",
+        "locatorFingerprint",
+        "requestedBase",
+        "creationCommit",
+        "primaryBranch",
+        "objectFormat",
+      ],
+      additionalProperties: false,
+    },
+    providerId: { type: "string", minLength: 1 },
+    number: { type: "integer", minimum: 1 },
+    url: { type: "string", minLength: 1 },
+    state: { const: "open" },
+    headSha: { type: "string", pattern: "^([0-9a-f]{40}|[0-9a-f]{64})$" },
+    baseSha: { type: "string", pattern: "^([0-9a-f]{40}|[0-9a-f]{64})$" },
+  },
+  required: ["repository", "providerId", "number", "url", "state", "headSha", "baseSha"],
+  additionalProperties: false,
+};
+
+export default function* PullRequest(props: Record<string, Json>): Operation<Json> {
+  // Before anything of this element's own exists — before a Repository is
+  // observed, before a checkout is selected, before retained Push evidence is
+  // read and long before a Git host is contacted. The body is what the pull
+  // request would say, and a body that never finished rendering must not become
+  // one that was published.
+  const body = (yield* hasContent()) ? yield* content() : "";
+
+  const repository = yield* currentRepository();
+  if (repository === undefined) {
+    throw new PullRequestAuthorityError(
+      "no-repository-context",
+      "it is written outside a lexical <Repository>, so there is no repository in scope for a " +
+        "pull request to be opened in.",
+    );
+  }
+
+  const outcome = yield* GitComposition.operations.upsertPullRequest({
+    repository,
+    workingDirectory: yield* cwd(),
+    // Normalized once, here: absence is `null` from this point on, because the
+    // durable request is JSON and a member that is sometimes missing would be a
+    // second shape rather than a value.
+    number: typeof props.number === "number" ? props.number : null,
+    title: typeof props.title === "string" ? props.title : "",
+    // Verbatim. What a document wrote is the pull request's body, and trimming
+    // or reflowing it here would publish something nobody authored.
+    body,
+    draft: props.draft === true,
+    // The Repository's own initial branch, retained when it was created, rather
+    // than whatever its default branch is at the host right now.
+    base:
+      typeof props.base === "string" && props.base !== "" ? props.base : repository.primaryBranch,
+  });
+  return pullRequestResultJson(outcome.result);
+}

packages/workflow/src/composition/errors.ts

@@ -187,6 +187,48 @@ export class GitOperationAuthorityError extends StaleInputError {
   }
 }
 
+/**
+ * A word from the fixed vocabulary a `<PullRequest>` authority refusal speaks.
+ *
+ * Every one of them is decided locally, before a Git host is observed. A pull
+ * request is a public statement about a branch that exists somewhere else, and
+ * the run has to be able to prove it put that branch there before it makes one.
+ */
+export type PullRequestAuthorityReason =
+  | "no-repository-context"
+  | "unnamed-branch"
+  | "missing-push-evidence"
+  | "conflicting-push-evidence"
+  | "unreadable-push-evidence";
+
+/**
+ * `<PullRequest>` is not authorized by what this run retained.
+ *
+ * A `StaleInputError`, on the same terms as {@link GitOperationAuthorityError}:
+ * a document cannot avoid a Repository context that was replaced or a retained
+ * Push result that stopped being readable, and later siblings must not run as
+ * though a pull request had been opened. None of these is a Git-host answer —
+ * every one of them is decided before anything is observed — so none of them is
+ * printable and none of them is journaled as an effect outcome.
+ *
+ * The sentence names the category and, where there is one, the remedy. It
+ * quotes no journal content, no retained record and nothing a caller presented:
+ * the evidence this refuses to read is exactly the evidence it must not repeat.
+ */
+export class PullRequestAuthorityError extends StaleInputError {
+  override name = "PullRequestAuthorityError";
+
+  readonly reason: PullRequestAuthorityReason;
+
+  constructor(reason: PullRequestAuthorityReason, sentence: string) {
+    super(
+      `<PullRequest> is not authorized against this run's retained state: ${sentence} Nothing ` +
+        "was observed at the Git host, and no pull request was created.",
+    );
+    this.reason = reason;
+  }
+}
+
 /**
  * Native Git failed in a way this provider does not recognize.
  *