Skip to content

Commit f9cf099

Browse files
authored
🏷️ Reconcile Git-host effects through one request-only surface (#480)
* 🔁 Reconcile every external forge effect through one shared operation (#297) A forge owns state no local transaction can enclose, so push, pull request and issue creation all face the same question after an interruption: did the previous attempt already succeed? They answer it once now. `reconcileForgeEffect()` derives external identity from the run and the expansion, observes before it mutates, and then adopts a proven compatible completion, performs a proven absence exactly once, or refuses conflict and permanent ambiguity. Temporary unavailability is its own ordinary failure, so document structure or explicit middleware — not this engine — decides on a retry. Provider selection is replaceable context and carries no completion authority. Each phase mints a one-use route and a separate opaque credential and puts the phase's evidence and its answer behind a capability that accepts only that credential, so a short circuit, a forged return, a substituted selection and a reused request complete nothing, and a throw after a real answer cannot take it away. The durable operation is named by a fingerprint of the complete detached request, so a changed kind, input or natural key diverges rather than consuming a retained result. * 🔒 Let only an accepted forge answer author a durable outcome (#297) Routing middleware could raise a ForgeConflictError before any provider was asked, and the coordinator — which classified authority by error name — wrote it into the journal as the effect's outcome, stack included. A handler could therefore retire an external effect as conflicted forever without a forge ever being contacted. An outcome now comes from exactly one place: an answer accepted through the execution-owned capability. The attempt records the failure it authored itself and reads it back by object identity, so no name and no class received from replaceable code can imitate one. A conflict, an ambiguity or an unavailability so accepted still publishes as the effect's failed result. Everything else that can raise on the way — selection, middleware, the provider's own body — publishes nothing, activates the existing fail-stop fence, and is reported as one fixed cause-free failure that repeats none of what was raised. The documentation also claimed Prompt as a consumer of this reconciler. It is not: #297 covers forge mutations, and Prompt keeps its own Agent-provider contract. * 🏷️ Reconcile Git-host effects through one request-only surface (#297) Two architecture corrections, made together because the second is only describable in the first's vocabulary. The product noun is Git host, not "forge": an external service that owns remote Git repositories and associated collaboration objects, distinct from the local Git capability and from the trusted workflow host. GitHub is one adapter of it. The modules, the public API, the durable type and the specifications say so, and nothing is left behind under the old name — no alias, no `forge_effect` reader, no forwarding module. Push, pull-request creation and issue creation are the three kinds; Prompt keeps its Agent-provider contract. A provider may support only some of them and refuses the rest from observation, before any remote work. The split provider-selection and invocation-capability surfaces are gone. They were individually harmless and jointly fatal: middleware could read a credential from the selection surface, take an invocation capability from the coordination surface, and answer a phase itself, and the journal then retained a completion no provider had produced. Reproduced against the reviewed head — zero provider calls, one adopted Yield reading `middleware-forgery`. There is now one request-only operation. Public middleware receives a frozen, one-use routing request, may inspect, refuse, narrow or delegate it, and its return is ignored; it gets no credential, no capability and no phase evidence, so there is nothing to combine. Each phase owns a descriptor under that same stable name, so the shared chain still applies while the default is that invocation's own terminal, reachable only through the continuation the selected provider's handler holds. * 🧹 Restore the Git-host boundary's authoritative answer path (#297) A mutation run proving GH10 discriminates a contextual return was captured by the preceding commit. The boundary reads only the answer its private terminal accepted; a middleware return value is evidence of nothing. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 4093071 commit f9cf099

10 files changed

Lines changed: 2891 additions & 20 deletions

File tree

‎architecture.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Existing documents and code get aligned to this section retroactively.
3535
| expansion | one logical evaluation of an authored executable element within a document execution |
3636
| expansion ID | a deterministic identifier for one logical expansion; restoring or retrying that expansion preserves the ID, while a distinct evaluation requested by the document receives another |
3737
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
38+
| Git host | an external service that owns remote Git repositories and associated collaboration objects such as branches, pull requests, and issues. GitHub is one Git-host adapter. A Git host is distinct from the local Git capability and the trusted workflow host |
3839
| printed error | an error printed into the document (`ErrorSegment`); data, not control flow |
3940
| failure | an error that propagates (`ComponentFailure`, `DocumentationError`) |
4041
| error mode | what an undecided error in a region becomes: `print` (printed into the document), `output` (fails the document execution; `<PrintErrors>` can print instead), `throw` (fails the document execution) |
@@ -836,7 +837,7 @@ data. The journal security policy filters a value before insertion. Training
836837
ingestion deliberately selects retained filtered history; it never receives the
837838
whole database merely because the database is retained.
838839

839-
Repository, filesystem, process, forge and Agent behavior reaches production
840+
Repository, filesystem, process, Git-host and Agent behavior reaches production
840841
code through contextual APIs. A provider adapter installs host behavior; shared
841842
modules neither detect a runtime nor fall back to the caller's host when a
842843
workflow capability is absent.
@@ -944,6 +945,58 @@ absence and refuses conflicting or permanently ambiguous state. Temporary
944945
provider unavailability may be retried or suspended by explicit middleware; it
945946
never authorizes a duplicate effect while completion is unknown.
946947

948+
Git-host mutations — Git push, pull-request creation and issue creation — share
949+
one provider-neutral reconciliation of that boundary, so a new Git-host effect
950+
kind supplies a request and a provider rather than a replay policy of its own.
951+
Prompt is not one of them: it keeps its own Agent-provider contract. A live
952+
Git-host attempt observes before it mutates, adopts a proven compatible
953+
completion, performs a proven absence exactly once, and refuses conflict and
954+
permanent ambiguity. A Git host need not implement every kind; one that does not
955+
refuses from observation, before any remote work.
956+
957+
Reconciliation is reached through exactly one stable contextual operation, and
958+
that is a deliberate correction rather than a simplification. An earlier design
959+
selected a provider on one surface and coordinated the invocation on a second;
960+
public middleware could read a credential from the first, take an invocation
961+
capability from the second, and answer a phase itself, and the journal then
962+
retained a completion no provider had produced. Two public surfaces that are
963+
individually harmless composed into completion authority.
964+
965+
The single operation is request-only. Public middleware receives one frozen,
966+
one-use routing request describing the complete detached request; it may read
967+
it, refuse it, install narrower policy, or delegate it, and the value it returns
968+
is ignored. It receives no credential, no capability, no answer operation and no
969+
phase evidence, so there is nothing to combine. Each phase builds its own API
970+
descriptor under that same stable name: sharing the name shares the middleware
971+
chain, while owning the descriptor owns the default, and that default is the
972+
invocation's own terminal. The selected provider's handler is installed at the
973+
terminal end of the chain, so its continuation — a parameter of its own
974+
generator — is the only route to that terminal. Through it the handler asks the
975+
terminal to inspect the exact request, calls the provider, and submits the
976+
answer. A handler that short-circuits, forges a return, substitutes or replays
977+
the request, or reconstructs the stable name reaches the provider's handler or
978+
the public refusing default, never the terminal.
979+
980+
The durable operation is named by a fingerprint of the complete detached
981+
request, so a changed kind, input or natural key diverges rather than consuming
982+
the result retained at the same position, and the provider's answer is parsed at
983+
the terminal before the durable executor returns, so a raw payload becomes a
984+
fixed protocol failure rather than journal content.
985+
986+
Only an answer the terminal accepted decides the effect. A conflict, a permanent
987+
ambiguity and a temporary unavailability so accepted publish the effect's failed
988+
result and replay as the same fixed local failure, rebuilt from its closed name
989+
rather than recognized by identity across loaded copies. Everything else that
990+
can raise before an answer is accepted — routing middleware, the provider
991+
handler, the provider's own body, an unsupported effect kind — publishes nothing
992+
and activates fail-stop under one fixed cause-free failure that repeats none of
993+
what was raised. The attempt decides which of the two it has by the identity of
994+
the failure it authored itself, never by a name or a class received from
995+
replaceable code: otherwise a handler could retire an effect as conflicted
996+
without a Git host ever being asked. Fail-stop rather than a bare refusal,
997+
because a live operation that appended nothing would leave the next one to
998+
append at its position.
999+
9471000
Every committed journal event references the current logical Workspace root.
9481001
Only committed event boundaries are checkpoints. A history fork cheaply retains
9491002
or clones the selected root, replays the inherited prefix under a compatible
@@ -2117,6 +2170,7 @@ Status is measured against main.
21172170
| caller-owned storage transaction | publishes several changes, including journal events, in one transaction nothing else enlists in | built on main |
21182171
| 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 |
21192172
| 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 |
2173+
| 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`, pull request and issue components are its consumers, unbuilt (#370, #295, #296) |
21202174
| 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 |
21212175
| `API.Service` / `startService()` | creates an authenticated, supervised loopback service attachment through a provider-neutral operation | built on main |
21222176
| 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 |

‎packages/workflow/mod.ts‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,29 @@
2424
* names no provider. The Deno host installs its own from
2525
* `@executablemd/workflow/deno`; nothing here imports it, and nothing here
2626
* imports SQLite, Deno or any other host.
27+
*
28+
* ## Git-host effects
29+
*
30+
* A **Git host** is an external service that owns remote Git repositories and
31+
* associated collaboration objects such as branches, pull requests and issues.
32+
* GitHub is one Git-host adapter; a Git host is not the local Git capability
33+
* and not the trusted workflow host.
34+
*
35+
* A Git host owns state no local transaction can enclose, so pushing, opening a
36+
* pull request and filing an issue all face the same question after an
37+
* interruption: did the previous attempt already succeed?
38+
* `reconcileGitHostEffect()` answers it once, for all three. A live attempt
39+
* observes under an identity derived from the run and the expansion, then
40+
* adopts a proven compatible completion, performs a proven absence exactly
41+
* once, or refuses. Prompt is not one of these effects and keeps its Agent
42+
* provider contract.
43+
*
44+
* `withGitHostProvider()` installs the provider that answers those phases. A
45+
* provider need not implement every kind: a plain Git server may support
46+
* `git-push` and refuse pull requests and issues. Routing is one contextual
47+
* operation that carries no completion authority — middleware may inspect,
48+
* narrow or refuse a request, and nothing it can hold or combine can answer
49+
* one.
2750
*/
2851

2952
export {
@@ -97,6 +120,47 @@ export type {
97120
} from "./src/composition/git-records.ts";
98121
export { useCompositionComponents } from "./src/composition/installation.ts";
99122

123+
export { GIT_HOST_API, GitHost } from "./src/git-host/api.ts";
124+
export type {
125+
GitHostApi,
126+
GitHostCall,
127+
GitHostPhase,
128+
GitHostPhaseDetails,
129+
GitHostProvider,
130+
GitHostRoutingRequest,
131+
} from "./src/git-host/api.ts";
132+
export {
133+
GitHostAmbiguousError,
134+
GitHostConflictError,
135+
GitHostProtocolError,
136+
GitHostProviderError,
137+
GitHostUnavailableError,
138+
} from "./src/git-host/errors.ts";
139+
export {
140+
completeGitHostEffectRequestJson,
141+
gitHostReconciliationRecordJson,
142+
parseCompleteGitHostEffectRequest,
143+
parseGitHostCompletion,
144+
parseGitHostEffectIdentity,
145+
parseGitHostObservation,
146+
parseGitHostReconciliationRecord,
147+
sameGitHostEffectRequest,
148+
} from "./src/git-host/records.ts";
149+
export type {
150+
CompleteGitHostEffectRequest,
151+
GitHostCompletion,
152+
GitHostDecision,
153+
GitHostEffectIdentity,
154+
GitHostEffectRequest,
155+
GitHostObservation,
156+
GitHostReconciliationRecord,
157+
} from "./src/git-host/records.ts";
158+
export {
159+
GIT_HOST_EFFECT,
160+
reconcileGitHostEffect,
161+
withGitHostProvider,
162+
} from "./src/git-host/effect.ts";
163+
100164
export { WorkspaceCoordination, WorkspaceCoordinationProviderError } from "./src/workspace/api.ts";
101165
export type { WorkspaceCoordinationApi } from "./src/workspace/api.ts";
102166
export { createDurableWorkspaceOperation } from "./src/workspace/effect.ts";
Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/**
2+
* The one Git-host middleware surface, and what a Git-host provider is.
3+
*
4+
* A **Git host** is an external service that owns remote Git repositories and
5+
* associated collaboration objects such as branches, pull requests and issues.
6+
* GitHub is one Git-host adapter. A Git host is distinct from the local Git
7+
* capability and from the trusted workflow host.
8+
*
9+
* There is exactly one contextual operation here, and it routes. Public
10+
* middleware receives one frozen, one-use request describing the complete
11+
* detached Git-host request; it may read it, refuse by throwing, install
12+
* narrower policy, or delegate that exact request onward. It receives no
13+
* credential, no capability, no answer operation and no phase evidence, and the
14+
* value it returns is ignored. Nothing a handler can hold or combine adds up to
15+
* completion authority — which is the whole reason there is one surface here
16+
* rather than two.
17+
*
18+
* A provider is provider-neutral by construction. It receives the frozen
19+
* normalized request and the evidence its phase is entitled to, and answers
20+
* with one of a closed set of shapes. Its credentials, transport and raw
21+
* responses stay inside its own closure.
22+
*
23+
* A Git host need not implement every effect kind. A plain Git server may
24+
* support `git-push` while supporting neither pull requests nor issues, and
25+
* says so by answering `observe()` with an `Err` named `GitHostProviderError`
26+
* before it performs any remote work. There is no capability discovery and no
27+
* negotiation: routing middleware selects among installed adapters, and an
28+
* unsupported kind is a refusal like any other.
29+
*/
30+
31+
import { type Api, createApi } from "@effectionx/context-api";
32+
import type { Operation, Result } from "effection";
33+
import { GitHostProviderError } from "./errors.ts";
34+
import type {
35+
CompleteGitHostEffectRequest,
36+
GitHostCompletion,
37+
GitHostObservation,
38+
} from "./records.ts";
39+
40+
/** The stable name every loaded copy composes through. */
41+
export const GIT_HOST_API = "executablemd.workflow.git-host";
42+
43+
/** Which half of one reconciliation attempt is running. */
44+
export type GitHostPhase = "observe" | "perform";
45+
46+
/**
47+
* What public routing middleware sees: one frozen, one-use routing request.
48+
*
49+
* It describes what is being asked of a Git host and where the request sits, so
50+
* a handler can route or refuse on the facts. It carries no evidence only the
51+
* provider is entitled to, and no member of it is a capability.
52+
*/
53+
export interface GitHostRoutingRequest {
54+
readonly intent: "route";
55+
readonly phase: GitHostPhase;
56+
readonly request: CompleteGitHostEffectRequest;
57+
}
58+
59+
/**
60+
* What the selected provider's handler is told, once, by the invocation itself.
61+
*
62+
* Reached only through that handler's own continuation, so the phase — and, for
63+
* a perform, the proven absence it acts on — is never visible to the middleware
64+
* the request travelled through.
65+
*/
66+
export type GitHostPhaseDetails =
67+
| { readonly phase: "observe"; readonly request: CompleteGitHostEffectRequest }
68+
| {
69+
readonly phase: "perform";
70+
readonly request: CompleteGitHostEffectRequest;
71+
readonly observation: GitHostObservation;
72+
};
73+
74+
/**
75+
* One message on the Git-host operation.
76+
*
77+
* Public middleware only ever receives {@link GitHostRoutingRequest}. The two
78+
* private members are how the selected provider's handler speaks to the
79+
* invocation's own terminal through the continuation it captured, and they are
80+
* declared here only because they travel on the same operation. Constructing
81+
* one grants nothing: the terminal is reachable from that continuation alone.
82+
*/
83+
export type GitHostCall =
84+
| GitHostRoutingRequest
85+
| { readonly intent: "inspect"; readonly routing: GitHostRoutingRequest }
86+
| {
87+
readonly intent: "answer";
88+
readonly routing: GitHostRoutingRequest;
89+
readonly answer: unknown;
90+
};
91+
92+
/**
93+
* What a Git host can be asked, in the order the shared state machine asks it.
94+
*
95+
* `observe` always runs first and answers what is provably there. `perform` is
96+
* reached only from proven absence, and receives that observation as the
97+
* evidence it acts on.
98+
*
99+
* Both answer with Effection's `Result`. The success channel carries a closed
100+
* normalized shape; the failure channel carries a temporary unavailability, or
101+
* — from `observe` only — a refusal of an effect kind this host does not
102+
* support. Anything else it puts there is outside the vocabulary it agreed to
103+
* speak.
104+
*/
105+
export interface GitHostProvider {
106+
observe(request: CompleteGitHostEffectRequest): Operation<Result<GitHostObservation>>;
107+
perform(
108+
request: CompleteGitHostEffectRequest,
109+
observation: GitHostObservation,
110+
): Operation<Result<GitHostCompletion>>;
111+
}
112+
113+
export interface GitHostApi {
114+
/**
115+
* Route one Git-host request.
116+
*
117+
* The public call answers nothing: a return value is not evidence, and
118+
* `reconcileGitHostEffect()` ignores it.
119+
*/
120+
route(call: GitHostCall): Operation<unknown>;
121+
}
122+
123+
/**
124+
* The public Git-host surface. Its own default always refuses.
125+
*
126+
* Invoking this descriptor with a captured request outside a live invocation
127+
* reaches this default and completes nothing. A live attempt invokes its own
128+
* descriptor, which shares this stable name — and so this middleware chain —
129+
* while terminating in that invocation's private authoritative terminal.
130+
*/
131+
export const GitHost: Api<GitHostApi> = createApi<GitHostApi>(GIT_HOST_API, {
132+
// deno-lint-ignore require-yield
133+
*route(): Operation<unknown> {
134+
throw new GitHostProviderError(
135+
"no Git host provider accepted this request, and this surface completes nothing on its own",
136+
);
137+
},
138+
});

0 commit comments

Comments
 (0)