Skip to content

Commit 83b0d9d

Browse files
committed
🔎 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
1 parent e408dca commit 83b0d9d

12 files changed

Lines changed: 1821 additions & 693 deletions

‎architecture.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +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 |
7172
| 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 |
7273
| checkpoint | a completed journal boundary associated with the logical Workspace root visible after that effect |
7374
| 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 |
@@ -906,8 +907,9 @@ transaction commits restores the recorded answer event without reaching the live
906907
controller and without consuming or publishing again.
907908

908909
Scheduling — automatic resume, watchers, unattended iteration and remote host
909-
selection — remains blocked on #301's supervised-workflow contract and is not
910-
part of this behavior.
910+
selection — is #300's and is not part of this behavior. Nothing here waits on
911+
it: a suspended run continues through `xmd workflow answer` followed by an
912+
explicit `xmd workflow resume`.
911913

912914
This contract folds issue #322's suspension effect into #367. Issue #322 no
913915
longer supplies a separate implementation prerequisite; its typed correlated
@@ -1270,6 +1272,25 @@ the inherited prefix under a compatible modified definition and appends new
12701272
history under a new run ID. It never rewinds external branches, pushes, pull
12711273
requests or provider state.
12721274

1275+
Reading what a Git host holds is not reconciling what it owns. A reconciliation
1276+
exists to mutate a remote at most once across interruption, and everything it
1277+
carries — the natural key, the pre-state, the observe-then-perform pair — is
1278+
there to decide whether an attempt already landed. A read decides nothing of the
1279+
kind: repeating it is safe, and a completed one restores from the journal. So a
1280+
Git-host evidence read is an ordinary durable effect, and the machinery that
1281+
makes a mutation exactly-once is deliberately absent rather than reused where it
1282+
would only add a second identity to keep in agreement.
1283+
1284+
What such a read must not do is answer partially. A collection the host
1285+
completed and a collection nobody could finish reading are opposite facts, and
1286+
only one of them is `[]`; a truncated list would report the first while meaning
1287+
the second, so an incomplete walk fails the read and retains no array at all.
1288+
The request crosses a public request-only route, so middleware may see it,
1289+
refuse it, or narrow what a run may read; the evidence crosses no public route
1290+
at all. What that route answers with is a request, and the terminal behind it
1291+
admits only the exact request object the host minted for the invocation now
1292+
running.
1293+
12731294
An external effect is judged by its retained record rather than by its type. A
12741295
completed Git-host reconciliation record replays without contacting a provider,
12751296
so a fork inherits it and the remote is mutated once; the record keeps the
@@ -3092,7 +3113,8 @@ Status is measured against main.
30923113
| `suspendFor()` | publishes one filtered suspension request, settles `suspended`, releases the executor lock, and re-enters the same wait without duplicating it | built on the #367 stack |
30933114
| `xmd workflow answer <run-id> <suspension-id> <json>` | retains one schema-validated value for one retained wait, taking no executor lock and changing no run state | built by #300 |
30943115
| `suspension_answer` durable effect | ends a wait from retained delivery state, publishing the answer and consuming that state in one transaction | built by #300 |
3095-
| workflow scheduling (watchers, unattended iteration, remote host selection) | — | blocked on #301 |
3116+
| `<PullRequest.Reviews>` · `<PullRequest.Comments>` · `<PullRequest.Checks>` | read the reviews, comments and checks a Git host already holds for one numbered pull request, completely or not at all | built by #576 |
3117+
| workflow scheduling (watchers, unattended iteration, remote host selection) | — | #300 |
30963118
| `<Result as>` | binds `{ok: true, value}` or `{ok: false, error}`; a failure becomes a bound value, not a raise | defined, unbuilt |
30973119
| error middleware (JS api) | retry · suspend · decline | defined, unbuilt |
30983120

‎packages/workflow/src/composition/components/PullRequestReads.ts‎

Lines changed: 135 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,23 @@
4444
*/
4545

4646
import { cwd } from "@executablemd/runtime";
47-
import type { FormDeclaration, InvocationForm, PropsSchema } from "@executablemd/core";
47+
import type {
48+
FormDeclaration,
49+
InvocationForm,
50+
JsonObject,
51+
PropsSchema,
52+
ReturnsSchema,
53+
} from "@executablemd/core";
4854
import type { Operation } from "effection";
4955
import type { Json } from "@executablemd/durable-streams";
5056
import { GitComposition } from "../git-api.ts";
5157
import { currentRepository } from "../context.ts";
5258
import { PullRequestReadError } from "../errors.ts";
5359
import { pullRequestReadResultJson } from "../pull-request-read-records.ts";
5460
import type { PullRequestReadKind } from "../pull-request-read-records.ts";
61+
import { PullRequestEvidence } from "../pull-request-evidence-api.ts";
62+
import { mintReadRequest } from "../pull-request-read-terminal.ts";
63+
import { getExpansion } from "@executablemd/core";
5564

5665
/** The component names, as a document writes them and a refusal names them. */
5766
export const REVIEWS_ELEMENT = "<PullRequest.Reviews>";
@@ -67,14 +76,121 @@ export const props: PropsSchema = {
6776
additionalProperties: false,
6877
};
6978

79+
const AUTHOR: JsonObject = { type: ["string", "null"] };
80+
const NULLABLE_TEXT: JsonObject = { type: ["string", "null"] };
81+
const NULLABLE_COUNT: JsonObject = { type: ["integer", "null"] };
82+
const SIDE: JsonObject = { enum: ["left", "right", null] };
83+
84+
function array(items: JsonObject): ReturnsSchema {
85+
return { type: "array", items };
86+
}
87+
88+
function closed(properties: JsonObject): JsonObject {
89+
return {
90+
type: "object",
91+
properties,
92+
required: Object.keys(properties),
93+
additionalProperties: false,
94+
};
95+
}
96+
7097
/**
71-
* No `returns`.
98+
* The evidence each component binds, exactly.
7299
*
73-
* Declaring one would compile a schema for an array whose item shapes are the
74-
* provider records, and a second description of those is a second contract to
75-
* keep in agreement. The provider parses what it retained; what reaches a
76-
* binding is that parsed value.
100+
* Declared rather than left open, and for two reasons. It is the boundary a
101+
* document reads these records through, so a member arriving that the contract
102+
* does not name would be a provider detail reaching a binding. And declaring
103+
* `returns` is what makes `as` mandatory — which is checked before the body
104+
* runs, so an invocation that forgot it is refused before a credential is read
105+
* or a request is sent.
77106
*/
107+
export const reviewsReturns: ReturnsSchema = array(
108+
closed({
109+
id: { type: "string" },
110+
author: AUTHOR,
111+
state: { enum: ["approved", "changes-requested", "commented", "dismissed", "pending"] },
112+
body: { type: "string" },
113+
submittedAt: NULLABLE_TEXT,
114+
commitSha: NULLABLE_TEXT,
115+
url: { type: "string" },
116+
}),
117+
);
118+
119+
export const commentsReturns: ReturnsSchema = array({
120+
oneOf: [
121+
closed({
122+
kind: { const: "conversation" },
123+
id: { type: "string" },
124+
author: AUTHOR,
125+
body: { type: "string" },
126+
createdAt: { type: "string" },
127+
updatedAt: { type: "string" },
128+
url: { type: "string" },
129+
}),
130+
closed({
131+
kind: { const: "review" },
132+
id: { type: "string" },
133+
reviewId: NULLABLE_TEXT,
134+
author: AUTHOR,
135+
body: { type: "string" },
136+
createdAt: { type: "string" },
137+
updatedAt: { type: "string" },
138+
url: { type: "string" },
139+
path: { type: "string" },
140+
diffHunk: { type: "string" },
141+
commitSha: { type: "string" },
142+
originalCommitSha: { type: "string" },
143+
line: NULLABLE_COUNT,
144+
side: SIDE,
145+
startLine: NULLABLE_COUNT,
146+
startSide: SIDE,
147+
inReplyToId: NULLABLE_TEXT,
148+
}),
149+
],
150+
});
151+
152+
export const checksReturns: ReturnsSchema = array({
153+
oneOf: [
154+
closed({
155+
kind: { const: "check-run" },
156+
id: { type: "string" },
157+
headSha: { type: "string" },
158+
name: { type: "string" },
159+
status: {
160+
enum: ["queued", "in_progress", "completed", "waiting", "requested", "pending"],
161+
},
162+
conclusion: {
163+
enum: [
164+
"success",
165+
"failure",
166+
"neutral",
167+
"cancelled",
168+
"skipped",
169+
"timed_out",
170+
"action_required",
171+
null,
172+
],
173+
},
174+
url: NULLABLE_TEXT,
175+
startedAt: NULLABLE_TEXT,
176+
completedAt: NULLABLE_TEXT,
177+
title: NULLABLE_TEXT,
178+
summary: NULLABLE_TEXT,
179+
text: NULLABLE_TEXT,
180+
}),
181+
closed({
182+
kind: { const: "commit-status" },
183+
id: { type: "string" },
184+
headSha: { type: "string" },
185+
name: { type: "string" },
186+
state: { enum: ["error", "failure", "pending", "success"] },
187+
description: NULLABLE_TEXT,
188+
url: NULLABLE_TEXT,
189+
createdAt: { type: "string" },
190+
updatedAt: { type: "string" },
191+
}),
192+
],
193+
});
78194
function read(kind: PullRequestReadKind, element: string) {
79195
return function* PullRequestRead(props: Record<string, Json>): Operation<Json> {
80196
// The props schema is what refuses a missing, fractional or non-positive
@@ -100,12 +216,24 @@ function read(kind: PullRequestReadKind, element: string) {
100216
);
101217
}
102218

103-
const result = yield* GitComposition.operations.readPullRequestEvidence({
219+
// Minted here, so the object the provider admits is the one this
220+
// invocation issued and nothing a handler can reconstruct.
221+
const expansion = yield* getExpansion();
222+
const issued = mintReadRequest(expansion.id, {
104223
repository,
105224
workingDirectory: yield* cwd(),
106225
number,
107226
kind,
108227
});
228+
229+
// Request-only. Middleware installed in scope sees exactly what is about to
230+
// be read and may refuse it by throwing, or delegate; what it answers with
231+
// is a request, so there is nothing here it could answer with instead of
232+
// the evidence. A request it did not receive from this invocation is not
233+
// one the terminal will act on.
234+
const asked = yield* PullRequestEvidence.operations.read(issued);
235+
236+
const result = yield* GitComposition.operations.readPullRequestEvidence(asked);
109237
return pullRequestReadResultJson(result);
110238
};
111239
}

‎packages/workflow/src/composition/installation.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,12 @@ import PullRequest, {
2929
import Issue, { props as issueProps, returns as issueReturns } from "./components/Issue.ts";
3030
import {
3131
checksForm,
32+
checksReturns,
3233
commentsForm,
34+
commentsReturns,
3335
props as pullRequestReadProps,
3436
reviewsForm,
37+
reviewsReturns,
3538
} from "./components/PullRequestReads.ts";
3639
import IssueTracker, { props as issueTrackerProps } from "./components/IssueTracker.ts";
3740

@@ -94,18 +97,21 @@ export function useCompositionComponents(): Operation<void> {
9497
name: "PullRequest.Reviews",
9598
origin: COMPOSITION_ORIGIN,
9699
props: pullRequestReadProps,
100+
returns: reviewsReturns,
97101
fn: formDispatcher(reviewsForm),
98102
},
99103
{
100104
name: "PullRequest.Comments",
101105
origin: COMPOSITION_ORIGIN,
102106
props: pullRequestReadProps,
107+
returns: commentsReturns,
103108
fn: formDispatcher(commentsForm),
104109
},
105110
{
106111
name: "PullRequest.Checks",
107112
origin: COMPOSITION_ORIGIN,
108113
props: pullRequestReadProps,
114+
returns: checksReturns,
109115
fn: formDispatcher(checksForm),
110116
},
111117
{
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
/**
2+
* The request-only route a pull-request evidence read passes through
3+
* (specs/workflow-workspace-spec.md §7.7).
4+
*
5+
* Public middleware is entitled to know what a document is about to read, and
6+
* to stop it: a host that narrows which pull requests a run may look at, a test
7+
* that refuses the network, a policy that allows reviews and not checks. So the
8+
* request crosses this Api, where anything installed in scope sees it and may
9+
* throw, delegate to `next`, or pass it along.
10+
*
11+
* What does not cross it is the evidence. This route answers with a *request*,
12+
* never with a review, a comment or a check, so there is no return value here
13+
* that could become what a document binds or what the journal retains. A
14+
* handler that wants to change the answer has nothing to change it to.
15+
*
16+
* ## Why the answer is an object rather than a value
17+
*
18+
* The request an invocation issues is minted by the host and kept in an
19+
* owner-held set. The terminal behind this route admits only that exact object.
20+
* A handler may return it; a handler that returns a copy with the same members,
21+
* a request another invocation issued, or one it built from the retained
22+
* journal is returning something the terminal has no record of minting, and the
23+
* read is refused rather than performed under an identity nobody proved.
24+
*
25+
* Structural equality would not do. Two invocations of `<PullRequest.Reviews>`
26+
* on the same number in the same document produce equal requests, and a
27+
* middleware that held the first and returned it in place of the second would
28+
* be choosing which invocation's evidence the second one binds.
29+
*/
30+
31+
import { type Api, createApi } from "@effectionx/context-api";
32+
import type { Operation } from "effection";
33+
import type { PullRequestReadRequest } from "./pull-request-read-records.ts";
34+
35+
/** The contextual name this route is reached under, across loaded copies. */
36+
export const PULL_REQUEST_EVIDENCE_API = "executablemd.workflow.pull-request-evidence";
37+
38+
export interface PullRequestEvidenceApi {
39+
/**
40+
* Observe the read a document is about to perform.
41+
*
42+
* Answers with the request to perform — which is the request it was given, or
43+
* a refusal. It never answers with evidence.
44+
*/
45+
read(request: PullRequestReadRequest): Operation<PullRequestReadRequest>;
46+
}
47+
48+
export const PullRequestEvidence: Api<PullRequestEvidenceApi> = createApi<PullRequestEvidenceApi>(
49+
PULL_REQUEST_EVIDENCE_API,
50+
{
51+
// deno-lint-ignore require-yield
52+
*read(request: PullRequestReadRequest): Operation<PullRequestReadRequest> {
53+
return request;
54+
},
55+
},
56+
);

0 commit comments

Comments
 (0)