Skip to content

Commit 2cdbb97

Browse files
committed
🔎 Ask one surface for a pull request, and name it by URL
Replaces the request-only route and invocation-private terminal with the topology `<Issue>` already has: one `PullRequestApi` carrying `read(url, options)` and `upsert(pullRequest, options)`, reached under `executablemd.workflow.pull-request`, where a provider is ordinary middleware. It recognizes the URLs it can act on, delegates the rest untouched, and once it matches, its answer and its refusal are final. Reads name a pull request by canonical URL. No `<Repository>`, no working directory, no attachment: the URL is the identity and the selected provider parses the repository and number out of it. Canonicalization is provider-neutral and happens first, so the component, the durable request and every adapter read one answer. Implicit selection is public `github.com`; an explicit `provider="github"` reaches the same path shape on a self-hosted host. `upsertPullRequest` moves off `GitComposition` onto the same surface and keeps returning the complete `PullRequestResult`. Issue answers with a URL alone because that is the whole of its portable contract; a pull request already has a stronger shipped one, and #301's create/update loop reads `number` back on its next pass. Which pull requests may be read is now operator configuration: `XMD_WORKFLOW_GITHUB_PULL_REQUESTS` with `allowed` and an optional `endpoint`, read once when the Deno host is constructed and refused rather than narrowed when it is malformed. `allowed` rather than `ceiling` — the shipped issues contract keeps its word, and an operator writes the list of places this host may reach. Absence authorizes no URL read and disables nothing else: the adapter is installed on every live or partial attachment, its read method delegates to the surface's base error, and `<PullRequest>` upserts on this run's own Push evidence, which no configuration grants or withdraws. Two things the fork evidence found. A `pull_request_read` was classified `unsupported-effect`, so no checkpoint at or after one could be forked; it joins `fetch` in the inheritable set for the same reason — it changed nothing at the host, and the record holds the collection itself. And the run was in the effect *name*, which made every inherited read a different effect: it stays in the retained request, where it says who asked, and leaves the name to the question. PRR27 forks at the completed read itself. The control fork with the inherited URL restores the collection and sends no second request; a fork overriding `--props-url` diverges at that position and neither restores nor binds the earlier evidence. The unchanged control is asserted first on purpose — without it the changed branch would diverge for reasons that have nothing to do with the URL. PRR19, PRR20/20b, PRR21, PRR25 and PRR28 replace the superseded terminal attacks; PRR23 now proves URL, discriminator and collection all name the effect. Architecture, both specifications and the PR description follow. Refs #576
1 parent 2c26588 commit 2cdbb97

25 files changed

Lines changed: 1706 additions & 1084 deletions

‎architecture.md‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Existing documents and code get aligned to this section retroactively.
6868
| effect transaction | the single atomic SQLite transaction that publishes one Workspace-local mutation together with that effect's journal result |
6969
| external effect | an effect whose provider-owned outcome cannot participate in the Workspace SQLite transaction and therefore requires a stable identity and provider reconciliation |
7070
| XMD-mediated HTTP read | one bounded, non-mutating HTTP request an authored document performs through the contextual Fetch capability, whose detached response is retained as an ordinary durable observation. It is distinct from an Agent's own network authority, which it does not grant, and from a reconciled mutating external effect, which it does not claim: an interruption before its record commits may repeat the read |
71-
| Git-host evidence read | one bounded, non-mutating read of a collection a Git host already holds about a named pull request — its reviews, its comments, or the checks on its head. It is authenticated with the host's own credential and paginated by the adapter, and it is *not* a reconciled external effect: it has no natural key, no pre-state and nothing to adopt, so it is an ordinary durable read whose interrupted attempt may repeat and whose completed record replays without contacting a provider. It answers completely or not at all — an empty collection and a collection nobody could finish reading are different answers |
71+
| Git-host evidence read | one bounded, non-mutating read of a collection a Git host already holds about the pull request a canonical URL names — its reviews, its comments, or the checks on its head. It needs no Repository in scope: the URL is the identity, and the selected provider parses the repository and number out of it. It is authenticated with the host's own credential, bounded by the operator's `allowed` list, and paginated by the adapter, and it is *not* a reconciled external effect: it has no natural key, no pre-state and nothing to adopt, so it is an ordinary durable read whose interrupted attempt may repeat, whose completed record replays without contacting a provider, and which a fork inherits. It answers completely or not at all — an empty collection and a collection nobody could finish reading are different answers |
7272
| object-source attachment | adapter-private composition data the trusted host builds for exactly one external-effect reconciliation, giving the selected provider authorized live access to local state the frozen request cannot describe — the Git objects a push publishes, and the retained locator it is authorized to reach. It is authenticated against the durable identity it belongs to and proven contained before its first use — the local state behind one can name further state, so the graph a provider could traverse through it is validated rather than assumed — held in that provider's own closure, disposed with the invocation, and is never durable, never part of a natural key and never visible to routing middleware |
7373
| checkpoint | a completed journal boundary associated with the logical Workspace root visible after that effect |
7474
| history fork | a new workflow run that replays a compatible journal prefix and continues from its checkpoint and Workspace root under a new immutable document definition |
@@ -1285,18 +1285,20 @@ What such a read must not do is answer partially. A collection the host
12851285
completed and a collection nobody could finish reading are opposite facts, and
12861286
only one of them is `[]`; a truncated list would report the first while meaning
12871287
the second, so an incomplete walk fails the read and retains no array at all.
1288-
The structural request crosses a public request-only route, so middleware may
1289-
see it, refuse it, or narrow what a run may read — refusal being the whole of
1290-
narrowing, since reshaping a request is not something the terminal will accept.
1291-
The evidence crosses no public route at all: there is no operation on any public
1292-
Api that returns it, because one would be an operation anything in scope could
1293-
answer without delegating. The components are built by the trusted host over a
1294-
terminal they capture in their closure, and the terminal admits only the exact
1295-
request object the live activation is holding — not one named by an expansion
1296-
identifier, which is stable across continuations and would let a handler present
1297-
a genuine request from an earlier execution as a current one. The attachment a
1298-
provider needs, the Repository record and the working directory, never appears
1299-
in a request at all.
1288+
Both questions about a pull request — what it holds, and what it should say —
1289+
are asked of one surface, and a provider is ordinary middleware around it. That
1290+
is the Issue surface's topology, adopted deliberately: an adapter recognizes the
1291+
URLs it can act on and delegates the rest, and once it matches, its validation
1292+
and its refusal are final. A refusal ends the request rather than starting a
1293+
search for another provider, because a search is how a document that named one
1294+
service quietly reaches a different one.
1295+
1296+
Authority here is the operator's `allowed` list, checked before a session is
1297+
opened, a credential is read or anything is sent. It bounds reads alone: an
1298+
upsert names a branch this run published rather than a URL a document wrote, and
1299+
its authority is this run's own matching Push evidence, which no configuration
1300+
grants or withdraws. "Authority ceiling" remains the word for the bound; what an
1301+
operator writes is the list of places this host is allowed to reach.
13001302

13011303
An external effect is judged by its retained record rather than by its type. A
13021304
completed Git-host reconciliation record replays without contacting a provider,

‎packages/cli/src/deno-workflow.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ import type { WorkflowRunDatabase } from "@executablemd/workflow";
3434
import type { HelperAssembly } from "@executablemd/workflow/credential-helper";
3535
import type { WorkflowHost } from "./workflow.ts";
3636
import { gitHubIssuesConfiguration } from "./github-issues-config.ts";
37+
import { gitHubPullRequestsConfiguration } from "./github-pull-requests-config.ts";
3738
import { useWorkflowAgentProfile } from "./workflow-agent.ts";
3839

3940
/** Where a run lives when nothing says otherwise. */
@@ -50,6 +51,9 @@ export function* useDenoWorkflowHost(helper: HelperAssembly): Operation<Workflow
5051
// host cannot use learns it before a document runs rather than in the middle
5152
// of one. Absent installs no issue provider at all.
5253
const gitHubIssues = yield* gitHubIssuesConfiguration();
54+
// Read once, here, for the same reason: an operator who wrote something this
55+
// host cannot use learns it before a document runs.
56+
const gitHubPullRequests = yield* gitHubPullRequestsConfiguration();
5357
return {
5458
useRunHost(): Operation<WorkflowExecutionTransitions> {
5559
return useWorkflowRunHost({ root });
@@ -63,6 +67,7 @@ export function* useDenoWorkflowHost(helper: HelperAssembly): Operation<Workflow
6367
attach<T>(database: WorkflowRunDatabase, operation: Operation<T>): Operation<T> {
6468
return withWorkflowWorkspace(database, operation, {
6569
...(gitHubIssues === undefined ? {} : { gitHubIssues }),
70+
...(gitHubPullRequests === undefined ? {} : { gitHubPullRequests }),
6671
helper,
6772
// Only a live or partial attachment reaches this, which is what keeps a
6873
// completed replay from starting an agent process to restore a turn it
Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
/**
2+
* Where the production host learns which pull requests it may read.
3+
*
4+
* A URL a document writes is composition data: it says which pull request is
5+
* wanted, not that this deployment allows reading it. What allows it is here,
6+
* beside the credential, and it is the operator's to state — so it is read from
7+
* the environment rather than from anything a run can influence.
8+
*
9+
* Absence authorizes no URL read, and that is fail-closed by construction: with
10+
* nothing allowed, `<PullRequest.Reviews>` and its two siblings reach
11+
* `PullRequestAPI`'s own base error and say that nothing handles the
12+
* destination. A deployment that wants to read pull requests says so.
13+
*
14+
* **It does not disable `<PullRequest>`.** An upsert names a branch this run
15+
* published rather than a URL a document wrote, and its authority is this run's
16+
* own matching Push evidence and the Git-host reconciliation behind it. Nothing
17+
* here is what admits it, so nothing here can withdraw it.
18+
*
19+
* Malformed configuration is refused rather than narrowed to what parsed. An
20+
* operator who wrote a list this host could not read has not authorized the
21+
* empty set — they have made a mistake, and running with fewer targets than
22+
* they wrote would hide it until the day it mattered.
23+
*
24+
* The member is `allowed`, not `ceiling`. "Authority ceiling" is what the
25+
* architecture calls the bound; what an operator writes is the list of places
26+
* this host is allowed to read, and naming it after the thing they are stating
27+
* is the difference between configuration and jargon. `XMD_WORKFLOW_GITHUB_ISSUES`
28+
* keeps `ceiling`: it is shipped, and renaming a live contract to match a new
29+
* one is a break with nothing behind it.
30+
*/
31+
32+
import { env as readEnv } from "@executablemd/runtime";
33+
import type { Operation } from "effection";
34+
import { canonicalPullRequestUrl } from "@executablemd/workflow";
35+
import type { GitHubPullRequestsOptions } from "@executablemd/workflow/deno";
36+
37+
/** The variable that configures GitHub pull-request reading. */
38+
export const GITHUB_PULL_REQUESTS_ENV = "XMD_WORKFLOW_GITHUB_PULL_REQUESTS";
39+
40+
/** What an operator wrote there, once it is something this host cannot use. */
41+
export class GitHubPullRequestsConfigError extends Error {
42+
override name = "GitHubPullRequestsConfigError";
43+
44+
constructor(sentence: string) {
45+
super(
46+
`${GITHUB_PULL_REQUESTS_ENV} is not usable: ${sentence} Expected JSON such as ` +
47+
`{"allowed":["https://github.com/owner/repository"],"endpoint":"https://api.github.com"} — ` +
48+
"allowed is required, endpoint is optional. Unset it to authorize no URL read.",
49+
);
50+
}
51+
}
52+
53+
/**
54+
* The canonical form of an API base, or `undefined` when it is not one.
55+
*
56+
* Looser than a container URL in exactly one way: a port is admitted, because a
57+
* loopback endpoint is how a deployment points this at something other than
58+
* GitHub's own. Credentials, a query and a fragment are refused for the same
59+
* reason they are refused everywhere else — none of them is part of naming a
60+
* place, and none is guessed at or stripped.
61+
*/
62+
function canonicalEndpoint(value: unknown): string | undefined {
63+
if (typeof value !== "string" || value === "") {
64+
return undefined;
65+
}
66+
let url: URL;
67+
try {
68+
url = new URL(value);
69+
} catch {
70+
return undefined;
71+
}
72+
if (url.protocol !== "https:" && url.protocol !== "http:") {
73+
return undefined;
74+
}
75+
if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") {
76+
return undefined;
77+
}
78+
if (url.hostname === "") {
79+
return undefined;
80+
}
81+
const path = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
82+
return `${url.protocol}//${url.host}${path}`;
83+
}
84+
85+
/**
86+
* The GitHub pull-request options this host is configured with, or none.
87+
*
88+
* Strict about shape and about the URLs it holds. An entry that is not the
89+
* canonical name of a container is refused here rather than at the first
90+
* request, because an operator reading a startup failure can fix it and a
91+
* document author reading a refusal mid-run cannot.
92+
*/
93+
export function* gitHubPullRequestsConfiguration(): Operation<
94+
GitHubPullRequestsOptions | undefined
95+
> {
96+
const written = yield* readEnv(GITHUB_PULL_REQUESTS_ENV);
97+
if (written === undefined || written === "") {
98+
return undefined;
99+
}
100+
let parsed: unknown;
101+
try {
102+
parsed = JSON.parse(written);
103+
} catch {
104+
throw new GitHubPullRequestsConfigError("it is not JSON.");
105+
}
106+
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
107+
throw new GitHubPullRequestsConfigError("it is not a JSON object.");
108+
}
109+
for (const key of Object.keys(parsed)) {
110+
if (key !== "allowed" && key !== "endpoint") {
111+
throw new GitHubPullRequestsConfigError(
112+
`it carries ${JSON.stringify(key)}, which is not a member.`,
113+
);
114+
}
115+
}
116+
const declared = Reflect.get(parsed, "allowed");
117+
if (!Array.isArray(declared) || declared.length === 0) {
118+
throw new GitHubPullRequestsConfigError(
119+
"its allowed is not a non-empty array of container URLs.",
120+
);
121+
}
122+
const allowed: string[] = [];
123+
for (const entry of declared) {
124+
const canonical = canonicalPullRequestUrl(entry);
125+
if (canonical === undefined) {
126+
throw new GitHubPullRequestsConfigError(
127+
"one of its allowed entries is not an http or https URL naming one container, free of " +
128+
"credentials, query and fragment.",
129+
);
130+
}
131+
allowed.push(canonical);
132+
}
133+
const written_endpoint = Reflect.get(parsed, "endpoint");
134+
if (written_endpoint === undefined) {
135+
return Object.freeze({ allowed: Object.freeze(allowed) });
136+
}
137+
const endpoint = canonicalEndpoint(written_endpoint);
138+
if (endpoint === undefined) {
139+
throw new GitHubPullRequestsConfigError(
140+
"its endpoint is not an http or https API base, free of credentials, query and fragment.",
141+
);
142+
}
143+
return Object.freeze({ allowed: Object.freeze(allowed), endpoint });
144+
}

0 commit comments

Comments
 (0)