Repository navigation
Commit f230e8f
authored
🔎 Let a workflow read the objections a pull request already holds (#580)
* 🔎 Let a workflow read the objections a pull request already holds
A network-denied reviewer judges what its prompt renders, so an objection the
document does not fetch is one the review never sees. `<PullRequest>` returns
only what it reconciled; reviews, comments and checks are separate reads, and
until now there was no supported way to make them — `<Fetch>` is credential-free
by design, one request per invocation, with no pagination, and cannot reach a
private repository at all.
Three self-closing components read them:
<PullRequest.Reviews number={pullRequest.number} as="reviews" />
<PullRequest.Comments number={pullRequest.number} as="comments" />
<PullRequest.Checks number={pullRequest.number} as="checks" />
One required `number`; the enclosing <Repository> and the contextual working
directory decide the rest, so no prop names a host and none carries a
credential. The host's own credential is acquired for the retained locator and
disposed with the invocation, and nothing of it, the endpoint, the raw response
or the pagination state is retained.
Complete or unavailable, and never in between. A transport failure, a rate
limit, a rejected credential, an ambiguous 404, malformed content, an unreadable
item, a next relation off the authorized origin and a walk still going at the
page limit all fail the read rather than binding a shorter list. An empty array
means the provider completed the collection and found none, which is the one
thing a truncated list would be indistinguishable from.
Three components rather than one, and three durable effects: completing one
manufactures neither of the others, and each replays and fails alone. A read is
*not* a reconciled Git-host effect — that engine exists for a mutation that must
adopt an interrupted attempt, and a read has no natural key, no pre-state and
nothing to perform. It is an ordinary durable read, so an interruption may
repeat its GETs and a completed replay restores the array without opening a
session.
Answers are held to the request. Checks observe the head first and read every
result at that exact SHA, each record carrying it, so evidence always says which
revision it describes; a payload naming another repository, number or head is a
protocol failure. Check runs and commit statuses keep separate vocabularies
under `kind`, because a status's `error` is not a run's `failure`.
Evidence is PRR1–PRR11, every one mutation-checked. Two of them were green for
the wrong reason first: PRR2 passed while the component's number check was dead
(the props schema is the real gate, so that check is gone), and PRR11 passed
against a completed replay that never re-entered the procedure until the root
Close was dropped.
That investigation found a real defect. The components asked `hasContent()` to
refuse a paired invocation, and it answered `true` for a self-closing one —
the contextual answer #369 documented as untrustworthy. They now declare
`forms: "self-closing"` and the engine builds the dispatcher, the way `<Dir>`
and `<File.Delete>` do.
Refs #576
* 🔎 Keep the evidence off the route the request travels
Revises the pull-request evidence read. The three-component product surface is
unchanged; what changes is what crosses which boundary, and what a record has to
prove before it becomes evidence.
The request now crosses a public contextual route,
`executablemd.workflow.pull-request-evidence`, and the evidence crosses nothing
public at all. Middleware may see exactly what is about to be read, refuse it,
narrow which reads a run performs, or delegate — and the route answers with a
*request*, so there is nothing there it could answer with instead. Behind it is
an exact-invocation terminal: the request is minted for one invocation and
branded with a private class field, so a copy carrying the same members, a
request another invocation issued, one rebuilt from the retained journal, and
one a handler kept from an earlier read are each refused before anything is
sent. Structural equality would not do — two elements reading the same number
produce identical requests.
Durable and live are now separate. The journal holds `GitPushRepositoryIdentity`
— the Repository identity without its Workspace checkout path — plus the number
and the collection, and the effect's fingerprint covers those same members. The
full Repository record and the working directory stay live provider-private
attachment data. Every parser is closed on exact membership rather than on
presence, so a payload one member wider than the contract is refused instead of
reaching a binding.
Normalization corrections: `reviewId` is nullable, because an inline comment can
belong to no review; a check run's link is `html_url` and a commit status's is
`target_url`; an identifier that cannot be held exactly is refused rather than
rounded into one naming a different object; the status, conclusion and state
vocabularies are closed TypeScript unions; and *unavailable* is told apart from
*protocol-invalid* — a host that did not answer versus one that answered about
the wrong subject. Every field an answer is authenticated by is now required:
reviews and comments must name their pull request, checks and statuses must name
the commit, and the pull request must name its own number and repository.
Each component declares the exact array it binds, which is what makes `as`
mandatory and refuses an invocation that forgot it before a credential is read.
The engine-owned self-closing form dispatch is unchanged.
Evidence is PRR1–PRR24 in `pull-request-read.test.ts`, including the five
terminal attacks, the exact URL and field mappings, a null review id, session
teardown, a failed read retaining no array, and a changed question being a
different effect. Three of the new cases were wrong before they were right: a
failed durable read *is* journaled (with a refusal and no `value`), a changed
request at a replayed position is a divergence rather than a fresh read, and a
plain `Error` from middleware escapes differently than a domain refusal.
Two repository rules caught real mistakes: the first terminal was a
module-scoped `WeakMap` — a process-lifetime registry shared by every run — and
the adapter returned `{ok}` unions instead of Effection `Result<T>`.
Architecture, both specifications, both inventories and the #300 scheduling
boundary are updated; scheduling is #300's rather than blocked on #301.
Refs #576
* 🔒 Give the evidence no public route to be answered on
Addresses the review of 83b0d9d. The bypass was real: the component routed its
request through the new request-only Api and then took the evidence from
`GitComposition.readPullRequestEvidence`, which is public and exported. Anything
in scope could answer it without delegating, and the fabricated collection
became what a document bound and the journal retained — the branded-request
check sat behind a door nobody had to walk through.
That operation is gone. There is no public Api that returns evidence. The three
components are built by the trusted host over a terminal and capture it in their
closure, so the only thing that can author a result is the host; `PRR25` asserts
both halves — the operation is absent from the public Api, and middleware
installed on that Api observes no read at all.
The public request is now structural: the retained Repository identity, the
number and the collection. The attachment a provider needs — the whole
Repository record and the working directory — goes from the component to the
terminal directly and appears in no request, so middleware never sees a host
path.
The retained result is the discriminated envelope: `{kind:"reviews",items}`,
`{kind:"comments",items}`, `{kind:"checks",headSha,items}`. Only a checks result
carries a head, and only `items` becomes the binding. The adapter builds it
directly — the collector is generic, so each branch produces its own item type
and nothing is narrowed back out of a union.
`PRR26` covers interruption in flight: a transport that reaches the wire and
suspends, the owning task halted, and then the session unwound, no successful
result or partial array retained, and a continuation performing the whole
collection. `PRR27` — the changed-request replay at one position — is not here,
and deliberately: see the handback.
Architecture, the workflow Workspace specification (§7.7) and the
executable-MDX specification all describe the corrected boundary; the last of
those had not been touched before.
Refs #576
* 🔒 Authenticate the request this activation is holding, not a name for it
Addresses the Architect's review of 1fff3bb.
The issuance check was `expansion.id`, and that identifier outlives one
activation. Middleware could keep a genuine request from one execution and hand
it back during the next execution of the same element, and `isReadRequestFor()`
would call it current. PRR28 is that attack: the first execution is halted on
the wire so the root stays open, the handler keeps the request it saw, and the
next execution of the same element receives it back.
The fix is smaller than what it replaces. The component creates one request
object for the activation it is running and keeps it; the terminal is given both
that object and whatever came back from the route, and reads only when they are
the same object. Identity needs no registry, so the branded-request module is
gone entirely — no `WeakMap`, no class brand, no name. A copy, a sibling's
request, a reconstructed one and a stale one are all simply a different object.
`expansion.id` still names the durable position; it no longer authenticates
issuance.
The route is renamed throughout: `PullRequestAPI` in `pull-request-api.ts`,
companion interface `PullRequestApi`, contextual name
`executablemd.workflow.pull-request`. "Evidence" stays where it belongs — on the
normalized review, comment and check records, the adapter that produces them,
and the module they live in. `upsertPullRequest` is untouched.
PRR28 is mutation-checked: replacing the identity comparison with a structural
one fails it, and fails PRR19 with it.
Architecture, the workflow Workspace specification and the executable-MDX
specification all describe exact live object identity and the new name. The
public request is still `{repository, number, kind}`, the attachment is still
private, the envelopes are unchanged, only `items` binds, and no public Api
returns evidence.
The second required case — a changed durable request at the same position — is
not here. See the handback: it needs a fork fixture in another package.
Refs #576
* 🔎 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
* 🩹 Hold a pull-request answer to the whole subject it was asked about
Three corrections to the URL-based reading surface.
The composition provider carried a `gitHub` source option that nothing read
after reading moved to its own middleware, so every consumer injecting a
transport through it reached the real host instead. It is removed, and its
consumers now inject through `gitHubPullRequests.access`, which is the seam
that is actually installed.
An answer was matched to its request by the trailing number alone, so a
response about someone else's pull request numbered the same was published as
this one's evidence. The adapter now compares the complete API subject —
endpoint, owner, repository, collection and number — and the loopback fixture
answers with the absolute subject a real host returns.
The specifications still described the superseded Repository-and-number
request. They describe the URL the run retains.
PRR7 covers the same-number, wrong-repository answer for reviews and for
conversation comments. PRR27's changed-URL fork writes its property after the
positional, so it is refused as a divergence at the checkpoint rather than for
its arguments.
* 🩹 Read a repository name in any casing, the way GitHub does
The subject check compared the answer's URL byte for byte, so a request naming
`OCTO/PROJECT` — which GitHub accepts — was refused as protocol-invalid when
the host answered about `octo/project`, its own canonical spelling. The
comparison is now part by part: the endpoint, the collection and the number are
exactly what was asked for, and the owner and repository are the same name in
any casing. That is the identity the head check already applied to `full_name`,
and it now shares the one helper.
PRR7 keeps its wrong-repository rejection and gains the border case: a
canonical answer to a differently cased request is read. Restoring a byte
comparison fails it, and accepting any name fails it too.
The fixture builds its foreign review through an overrides parameter instead of
a cast.
* 🧪 Prove every published URL is the one a person opens
PRR3 asserted that bodies and messages survive normalization byte for byte, but
nothing held the links to their source fields. A payload carries three URL
families — what a person opens, what the API answers on, and where a build
lives — and a reader that published the wrong one would send a reviewer to JSON
or to a CI page instead of to the objection they were shown.
PRR3b gives each family a visibly distinct value and pins all six answers: a
review, a conversation comment and an inline comment are opened at `html_url`
rather than at the subject URL beside it; a check run is opened at `html_url`
and stays null without one, because `details_url` names a different place and
is not a substitute; a commit status is opened at `target_url` and stays null
without one. An inline comment left outside a review carries an explicit
`pull_request_review_id: null`, and it is an ordinary comment — retained with a
null review rather than dropping the collection.
Each answer discriminates: six independent mutations, one per field, each fail
this case and nothing else. No production change was needed.
---------
Co-authored-by: Taras Mankovski <[email protected]>1 parent d58c3db commit f230e8f
32 files changed
Lines changed: 4286 additions & 84 deletions
File tree
- packages
- cli
- src
- tests
- support
- workflow
- src
- composition
- components
- deno
- composition
- workspace
- lifecycle
- tests
- support
- scripts
- specs
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
68 | 68 | | |
69 | 69 | | |
70 | 70 | | |
| 71 | + | |
71 | 72 | | |
72 | 73 | | |
73 | 74 | | |
| |||
906 | 907 | | |
907 | 908 | | |
908 | 909 | | |
909 | | - | |
910 | | - | |
| 910 | + | |
| 911 | + | |
| 912 | + | |
911 | 913 | | |
912 | 914 | | |
913 | 915 | | |
| |||
1270 | 1272 | | |
1271 | 1273 | | |
1272 | 1274 | | |
| 1275 | + | |
| 1276 | + | |
| 1277 | + | |
| 1278 | + | |
| 1279 | + | |
| 1280 | + | |
| 1281 | + | |
| 1282 | + | |
| 1283 | + | |
| 1284 | + | |
| 1285 | + | |
| 1286 | + | |
| 1287 | + | |
| 1288 | + | |
| 1289 | + | |
| 1290 | + | |
| 1291 | + | |
| 1292 | + | |
| 1293 | + | |
| 1294 | + | |
| 1295 | + | |
| 1296 | + | |
| 1297 | + | |
| 1298 | + | |
| 1299 | + | |
| 1300 | + | |
| 1301 | + | |
| 1302 | + | |
1273 | 1303 | | |
1274 | 1304 | | |
1275 | 1305 | | |
| |||
3092 | 3122 | | |
3093 | 3123 | | |
3094 | 3124 | | |
3095 | | - | |
| 3125 | + | |
| 3126 | + | |
3096 | 3127 | | |
3097 | 3128 | | |
3098 | 3129 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
34 | 34 | | |
35 | 35 | | |
36 | 36 | | |
| 37 | + | |
37 | 38 | | |
38 | 39 | | |
39 | 40 | | |
| |||
50 | 51 | | |
51 | 52 | | |
52 | 53 | | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
53 | 57 | | |
54 | 58 | | |
55 | 59 | | |
| |||
63 | 67 | | |
64 | 68 | | |
65 | 69 | | |
| 70 | + | |
66 | 71 | | |
67 | 72 | | |
68 | 73 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
0 commit comments