Skip to content

Commit 0bb738f

Browse files
committed
✨ Advance a branch a run already published, when the remote is behind it
A workflow publishes one branch repeatedly: an iteration commits, pushes, commits again and pushes again. The second push found the destination naming another commit and refused it as a conflict, so a supervised loop could publish its branch exactly once (#588). A destination naming a commit that is anywhere in the ancestry of the one being published is now a performable pre-state. The push itself is unchanged — the same exact `<commit>:<destination>` refspec, which native Git applies only where it fast-forwards, with no force, no lease, no upstream option and nothing local rewritten. Equality still adopts, absence still performs, and anything else is still a conflict. The ancestry is proved inside the already-authenticated, contained object source, out of the objects that source holds, by one local question with two answers. Nothing is fetched to answer it, so an observed commit the source cannot read is an ordinary conflict; a proof that reaches neither answer is a boundary failure rather than a finding about the remote. The retained pre-state gains a third closed shape carrying the predecessor and `relation: "ancestor"`. The two existing shapes are written byte-for-byte as they were, and a record pairing a decision with a pre-state that cannot support it — a relation beside a proven absence, an unknown relation, an undeclared member, an adoption carrying a relation, a performance over an unattested predecessor — still fails closed. `<PullRequest>` now scans the whole successful history rather than refusing at the first older Push for the same branch: the record naming this iteration's commit authorizes wherever it appears, an earlier publication decides only which refusal an unauthorized pull request gets, and an unreadable relevant record still wins.
1 parent f230e8f commit 0bb738f

9 files changed

Lines changed: 865 additions & 66 deletions

File tree

‎architecture.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1143,7 +1143,24 @@ path, so a completed replay reaches no provider and performs no such proof. A
11431143
graph that leaves what the run authenticated is a boundary failure: it publishes
11441144
no outcome, repeats no authored path, and activates fail-stop. It is rejected
11451145
rather than repaired, because editing authored state to make it acceptable would
1146-
publish from state the run wrote on the author's behalf. The Workspace transaction such an effect opens is read-only and is
1146+
publish from state the run wrote on the author's behalf.
1147+
1148+
That same contained source is what decides whether a branch may advance. A
1149+
destination naming another commit is not by itself somebody else's work: a
1150+
supervised run publishes one branch repeatedly, and the ordinary case is a
1151+
remote tip the commit being published was built on top of. So ancestry is proved
1152+
where the objects already are — inside the authenticated source, out of the
1153+
commits it already holds, by one local question whose only answers are ancestry
1154+
and divergence. A proven ancestor is a performable pre-state, published over by
1155+
the same exact non-force refspec a proven absence gets; an equal destination is
1156+
adopted with nothing performed; and compatibility that was not proved — a
1157+
divergent commit, or one the source does not hold — is a conflict. Nothing is
1158+
fetched to prove it, because an object retrieved to answer the question would be
1159+
evidence the question created, and a proof that reaches neither of its two
1160+
answers is infrastructure rather than a finding about the remote. The relation,
1161+
not the traversal that found it, is what the record keeps.
1162+
1163+
The Workspace transaction such an effect opens is read-only and is
11471164
closed before the host is observed: no transaction is claimed across the
11481165
Workspace and the external service, and reconciliation rather than a distributed
11491166
transaction is what makes an interrupted attempt reach the host once.
@@ -3106,8 +3123,8 @@ Status is measured against main.
31063123
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack and Repository/Worktree composition on the #293 stack; process capabilities unbuilt (#218) |
31073124
| `<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 |
31083125
| 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 |
3109-
| `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 |
3110-
| `<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`, then the machine's own `gh` login, 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 |
3126+
| `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. A destination proven absent is published to once and one already naming this exact commit is adopted; one naming a commit that same authenticated source proves is in this commit's ancestry is a performable pre-state, published over by the same exact non-force refspec and retained as the predecessor with the attested relation, while a divergent commit and one the source cannot read are both conflicts and nothing is fetched to decide either | built on the #370 stack, Deno provider only |
3127+
| `<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 of the whole successful history that requires each relevant record's natural key, inputs and result to describe one publication; a branch is published repeatedly, so an earlier publication of it at an earlier commit is history rather than disagreement, and it decides only which refusal an unauthorized pull request gets — conflicting when this iteration's record is absent and one for another commit is there, missing when none is, and unreadable whenever a relevant record cannot be read whole, each failing 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`, then the machine's own `gh` login, 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 |
31113128
| `<Issue>` | asks one of two questions, decided by its own shape, through a boundary of its own rather than the Git host's. Self-closing with `url` reads that issue and binds `{ url, title, description, tags, assignee }`; paired with `title` upserts and binds exactly `{ url }`, its rendered content being the description. There is no `description` prop. Props are exactly `url`, `title`, optional `tags`, optional `assignee` and — on a read only — optional `provider`; no repository/token/label/milestone/project/comment/close or approval prop. Both forms render nothing. The form is decided before the tracker is read, before any provider is asked and before an `issue_effect` record exists, and that is where a mixed `url`+`title`, a read carrying content or `tags`/`assignee`, an upsert with no content, an upsert naming a `provider`, and an element that is neither are all refused. A read needs no tracker — its URL is the identity; an upsert requires the nearest lexical `<IssueTracker>` and takes its discriminator only from there. The tracker carries a credential-free `url` and an optional `provider`; the URL is canonicalized — a credential, a query and a fragment are refused rather than stripped — and a nested tracker replaces the whole value for its descendants, never merging members, with the enclosing one restored on leaving. It is composition data, not authority: the provider holds an adapter-private ceiling beside its credentials, admitted before it connects, so a target outside it sends nothing. One stable contextual operation, `executablemd.workflow.issue`, with `read(url, options)` and `upsert(issue, options)`; a provider is ordinary middleware around it, matching its own URLs without a discriminator and only its own name with one, independently per member, with no host-side resolution. Once middleware matches it owns the answer — it never delegates afterwards, and nothing catches its refusal to try somebody else — and a request everyone delegated reaches `NoIssueProvider` unchanged. `issue_effect` records an operation discriminator with the normalized request and result; both forms replay without reaching `IssueApi` and therefore without network access; only an upsert derives an idempotency key, from the operation, the canonical target and the run's own effect identity. Retention excludes credentials, endpoints, payloads, provider identities, origin markers and host paths. Observing, adopting, creating once and recovering an interrupted creation are the provider's, because they are knowledge about what a service can prove; title is never identity, and tags are a code-point-sorted set. The Deno workflow host installs configured GitHub middleware and installs none otherwise, so absence of configuration is fail-closed | built on the #296 stack; GitHub middleware, Deno host |
31123129
| workflow lifecycle inspection and control | reads status/list/history without advancing a run, recovering a private copy when a crashed source needs rollback; enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | direct read-only inspection and control built on the #367 stack; coordinated recovered inspection built on the #513 stack, Deno provider only |
31133130
| 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 |

‎packages/workflow/src/composition/git-push-records.ts‎

Lines changed: 54 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -87,11 +87,25 @@ export interface GitPushNaturalKey {
8787
readonly destinationRef: string;
8888
}
8989

90-
/** What the destination ref held before this attempt, as far as it was proven. */
91-
export interface GitPushPreState {
92-
/** The commit the destination named, or `null` when it was proven absent. */
93-
readonly remoteCommit: string | null;
94-
}
90+
/** The one relation a pre-state may attest between the predecessor and the source. */
91+
export const ANCESTOR = "ancestor";
92+
93+
/**
94+
* What the destination ref held before this attempt, as far as it was proven.
95+
*
96+
* Three closed shapes, and the third is what makes an ordinary fast-forward
97+
* ordinary. A destination proven absent is `null`. A destination naming a
98+
* commit is that commit — and when the provider proved inside its own
99+
* authenticated object source that the commit is somewhere in the source's
100+
* ancestry, the pre-state says so. That attestation is the whole of what
101+
* authorizes the existing exact non-force push against a branch that already
102+
* exists: the fact was established locally, once, before anything was
103+
* published, and the record keeps it rather than the traversal that found it.
104+
*/
105+
export type GitPushPreState =
106+
| { readonly remoteCommit: null }
107+
| { readonly remoteCommit: string }
108+
| { readonly remoteCommit: string; readonly relation: typeof ANCESTOR };
95109

96110
/** What the destination ref holds now. */
97111
export interface GitPushObservations {
@@ -130,6 +144,8 @@ const NATURAL_KEY_MEMBERS = ["repository", "remote", "destinationRef"] as const;
130144

131145
const PRE_STATE_MEMBERS = ["remoteCommit"] as const;
132146

147+
const ANCESTOR_PRE_STATE_MEMBERS = ["remoteCommit", "relation"] as const;
148+
133149
const OBSERVATION_MEMBERS = ["remoteCommit"] as const;
134150

135151
const RESULT_MEMBERS = [
@@ -199,7 +215,12 @@ export function gitPushNaturalKeyJson(key: GitPushNaturalKey): Json {
199215
}
200216

201217
export function gitPushPreStateJson(preState: GitPushPreState): Json {
202-
return { remoteCommit: preState.remoteCommit };
218+
// The two shapes that existed before an attested relation did are written
219+
// exactly as they always were, so a record this version writes for an absent
220+
// or an equal destination is byte-for-byte one an earlier version wrote.
221+
return "relation" in preState
222+
? { remoteCommit: preState.remoteCommit, relation: preState.relation }
223+
: { remoteCommit: preState.remoteCommit };
203224
}
204225

205226
export function gitPushObservationsJson(observations: GitPushObservations): Json {
@@ -329,11 +350,26 @@ export function parseGitPushNaturalKey(value: unknown): GitPushNaturalKey | unde
329350
return Object.freeze({ repository, remote, destinationRef });
330351
}
331352

332-
/** The pre-state this value describes, or `undefined` when it describes none. */
353+
/**
354+
* The pre-state this value describes, or `undefined` when it describes none.
355+
*
356+
* The two variants are read separately so each stays closed. A relation is a
357+
* claim about a commit, so it means nothing beside a destination proven absent;
358+
* a word other than `ancestor` is a relation this version cannot account for;
359+
* and either variant carrying a member it does not declare describes something
360+
* else entirely.
361+
*/
333362
export function parseGitPushPreState(
334363
value: unknown,
335364
format: GitObjectFormat,
336365
): GitPushPreState | undefined {
366+
const attested = members(value, ANCESTOR_PRE_STATE_MEMBERS);
367+
if (attested !== undefined) {
368+
const remoteCommit = gitObjectId(attested.remoteCommit, format);
369+
return remoteCommit === undefined || attested.relation !== ANCESTOR
370+
? undefined
371+
: Object.freeze({ remoteCommit, relation: ANCESTOR });
372+
}
337373
const record = members(value, PRE_STATE_MEMBERS);
338374
if (record === undefined) {
339375
return undefined;
@@ -429,10 +465,14 @@ export function parseGitPushResult(
429465
* effect-specific: that each of the three JSON members is a Push shape, that
430466
* the two readings agree, and that the decision is one the pre-state supports.
431467
*
432-
* The decision and the pre-state are one fact. `performed` means this run found
433-
* the destination absent and published to it; `adopted` means the destination
434-
* already named this exact commit. A record pairing either word with the other
435-
* word's pre-state describes a reconciliation the state machine cannot reach.
468+
* The decision and the pre-state are one fact. `performed` means this run
469+
* published, and it publishes for two reasons: the destination was proven
470+
* absent, or it named a commit the provider attested is in this source's
471+
* ancestry. `adopted` means the destination already named this exact commit,
472+
* and nothing was performed — an attested relation beside it would be a record
473+
* claiming the destination both was and was not already there. A record pairing
474+
* a word with a pre-state that does not support it describes a reconciliation
475+
* the state machine cannot reach.
436476
*/
437477
export function parseGitPushRecord(
438478
record: GitHostReconciliationRecord,
@@ -448,9 +488,10 @@ export function parseGitPushRecord(
448488
if (observations.remoteCommit !== result.observedRemoteCommit) {
449489
return undefined;
450490
}
491+
const attested = "relation" in preState;
451492
const supported =
452493
record.decision === "performed"
453-
? preState.remoteCommit === null
454-
: preState.remoteCommit === result.sourceCommit;
494+
? preState.remoteCommit === null || attested
495+
: !attested && preState.remoteCommit === result.sourceCommit;
455496
return supported ? Object.freeze({ decision: record.decision, result }) : undefined;
456497
}

0 commit comments

Comments
 (0)