Skip to content

Commit c4646da

Browse files
committed
📐 Separate the Issue boundary from the Git-host contract it is not
Revises a3249d1. The scenario matrix and the recovery evidence are unchanged. The Issue paragraphs had been written into the middle of the Git-host narrative, between "reconciliation is reached through exactly one stable contextual operation" and the terminal that operation ends in — so a reader met a claim about `<Issue>` while reading #297's contract, and the two boundaries blurred into one. They now follow that contract rather than interrupt it, and open by naming the difference: everything above is a shared state machine, one request-only surface, phases and a private terminal, and `<Issue>` has none of it because knowing whether an issue already exists is knowledge about one service rather than about external effects in general. The Git-host text itself is untouched. `upsertIssue` and `IssueEffectRequest` leave the package root. The envelope is how `<Issue>` reaches a provider, not something another package composes. The D1 explanation was wrong and is replaced rather than reworded. It claimed that fork compatibility does not reread the candidate definition; it does. What is true is narrower and compositional: the request fingerprint covers every member of the request, the durable operation is named by that fingerprint, and a durable stream diverges when the name at a position is not the one the history holds there. Only the first is this package's to prove, and `issue-records.test.ts` proves it by varying one member at a time; the second is a line at the call site and the third is the stream's own contract. What the suite does not do is stage the three end to end, and both the test and the scenario document now say so instead of explaining a mechanism I had wrong.
1 parent 5ce7027 commit c4646da

4 files changed

Lines changed: 75 additions & 43 deletions

File tree

‎architecture.md‎

Lines changed: 48 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1058,31 +1058,6 @@ performs a proven absence exactly once, and refuses conflict and permanent
10581058
ambiguity. A Git host need not implement every kind; one that does not refuses
10591059
from observation, before any remote work.
10601060

1061-
Issue creation is a boundary of its own, and that separation is the point rather
1062-
than an accident of layering. An Issue provider does not necessarily own a Git
1063-
repository — Atlassian issue tracking owns none — so an Atlassian issue could
1064-
not truthfully execute or persist as a Git-host effect. `<Issue>` therefore has
1065-
its own contextual routing operation and its own durable effect type,
1066-
`issue_effect`, and reuses the reconciliation mechanics above internally rather
1067-
than by sharing the Git-host boundary. What is Issue-owned, and therefore an
1068-
Issue compatibility boundary, is the stable API name, the normalized request,
1069-
the provider identity, the natural key, the result and the durable effect type.
1070-
1071-
Which external system an issue is requested in is lexical context, and whether
1072-
that target is authorized is the provider's. The nearest tracker supplies a
1073-
canonical target URL and an optional provider discriminator; the adapter-private
1074-
ceiling installed beside the credential decides whether that target may be
1075-
reached at all. A tracker narrows within the ceiling and can never widen it,
1076-
which is what keeps a replaceable context from being a grant.
1077-
1078-
A provider is ordinary middleware around one operation rather than an entry in a
1079-
registry, and that is the whole mechanism: there is no resolver to consult, no
1080-
phase protocol to speak and no terminal to reach. What the boundary keeps for
1081-
itself is small — it derives the idempotency key, wraps one call durably, and
1082-
retains the URL. Everything about what a particular service can prove, including
1083-
not creating an issue twice, is the middleware's, because that knowledge cannot
1084-
be written once for services that do not agree on what an issue is.
1085-
10861061
Reconciliation is reached through exactly one stable contextual operation, and
10871062
that is a deliberate correction rather than a simplification. An earlier design
10881063
selected a provider on one surface and coordinated the invocation on a second;
@@ -1163,6 +1138,54 @@ without a Git host ever being asked. Fail-stop rather than a bare refusal,
11631138
because a live operation that appended nothing would leave the next one to
11641139
append at its position.
11651140

1141+
Issue creation is a separate boundary, and not that one. Everything above is the
1142+
Git-host contract: a shared state machine, one request-only surface, phases, and
1143+
a private terminal that is the only thing able to author an outcome. `<Issue>`
1144+
has none of it, and none of it is missing.
1145+
1146+
An Issue provider does not necessarily own a Git repository — Atlassian issue
1147+
tracking owns none — so an Atlassian issue could not truthfully execute or
1148+
persist as a Git-host effect. `<Issue>` therefore reaches its own stable
1149+
contextual operation, `executablemd.workflow.issue`, whose only member is
1150+
`upsert(issue, options)`, and journals its own durable effect type,
1151+
`issue_effect`. What is Issue-owned, and therefore an Issue compatibility
1152+
boundary, is that API name, the normalized request, the idempotency key, the
1153+
result and the effect type.
1154+
1155+
The difference is not only which name is called. A Git-host provider is selected
1156+
by the reconciliation and answers through a terminal it cannot address directly,
1157+
because the state machine is shared and the journal may hold only what that
1158+
terminal accepted. An Issue provider is ordinary middleware: it composes
1159+
`IssueApi.around(...)`, reads the destination it was handed, and either handles
1160+
the request or delegates it untouched. There is no registry, no resolver, no
1161+
phase protocol and no terminal. What would have been the state machine's job is
1162+
the middleware's instead, because knowing whether an issue already exists is
1163+
knowledge about one service rather than about external effects in general, and a
1164+
shared machine would have to be told it by every adapter that disagreed.
1165+
1166+
So the Issue boundary keeps little for itself: it derives an idempotency key
1167+
from the canonical target and the run's own effect identity, wraps one call
1168+
durably, validates that what came back is a URL and nothing else, and retains
1169+
it. Replay answers from the journal without calling the operation at all. What
1170+
it does not promise is that the service was touched once — observing before
1171+
mutating, adopting a compatible issue, creating once, recovering an interrupted
1172+
creation and refusing conflict and ambiguity all belong to the middleware, and
1173+
the key is what this side hands over so the middleware can make it true.
1174+
1175+
Which external system an issue is requested in is lexical context, and whether
1176+
that target is authorized is the provider's. The nearest tracker supplies a
1177+
canonical target URL and an optional provider discriminator; the adapter-private
1178+
ceiling installed beside the credential decides whether that target may be
1179+
reached at all. A tracker narrows within the ceiling and can never widen it,
1180+
which is what keeps a replaceable context from being a grant.
1181+
1182+
Without a discriminator each provider matches its own URLs; with one, only the
1183+
provider of that name may act, which is how a self-hosted deployment is
1184+
addressed. Once middleware matches it owns the answer: it never delegates
1185+
afterwards, and nothing catches its refusal to try somebody else, because a
1186+
search is how a document that named one service quietly reaches another. A
1187+
destination every provider delegated reaches the operation's own base error.
1188+
11661189
Every committed journal event references the current logical Workspace root.
11671190
Only committed event boundaries are checkpoints. A history fork copies the
11681191
selected root and the roots the inherited prefix names into the new run, replays

‎packages/workflow/mod.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -210,8 +210,6 @@ export {
210210
currentIssueTracker,
211211
} from "./src/issue/context.ts";
212212
export { ISSUE_EFFECT } from "./src/issue/effect-type.ts";
213-
export { upsertIssue } from "./src/issue/effect.ts";
214-
export type { IssueEffectRequest } from "./src/issue/effect.ts";
215213
export {
216214
IssueAmbiguousError,
217215
IssueConflictError,

‎packages/workflow/tests/issue-records.test.ts‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,28 @@
11
/**
22
* Tier WI — what a retained issue record is, and what names it.
33
*
4-
* D1 lives here rather than in a scenario document, and the reason is worth
5-
* stating: the claim is that a *changed request* cannot consume the result
6-
* retained for a different one, and that cannot be staged by running an edited
7-
* document against a retained journal. An edited root is a fork (§11), and a
8-
* fork replays the retained expansion positionally rather than re-reading what
9-
* the new document says — so a scenario written that way reports the first
10-
* attempt's URL and passes while proving the opposite.
4+
* D1 lives here rather than in a scenario document, and the reason is that the
5+
* claim is compositional. "A changed request cannot consume the result retained
6+
* for a different one" is three facts stacked:
117
*
12-
* What actually decides it is the durable name, which is a function of the
13-
* request. So the request is varied one member at a time, here, where every
14-
* member can be named.
8+
* 1. the request fingerprint covers every member of the request — the canonical
9+
* target, the discriminator, the run, the expansion, and each of the four
10+
* authored fields;
11+
* 2. the durable operation is *named* by that fingerprint
12+
* (`upsertIssue()` in `src/issue/effect.ts`); and
13+
* 3. a durable stream diverges when the name at a position is not the name the
14+
* history holds there, which is `@executablemd/durable-streams`' own
15+
* contract rather than this package's.
16+
*
17+
* Only the first is this module's to prove, and it is what these tests vary one
18+
* member at a time. The second is one line at the call site and is read there.
19+
* The third belongs to the stream and is proven where the stream is.
20+
*
21+
* Staging the composition end to end would mean offering one journal to a
22+
* second execution whose request differs. That is worth having and is not what
23+
* the scenario documents do today: a scenario that swapped root documents
24+
* between attempts did not exercise the mismatch path in this suite's fixture,
25+
* so the claim is recorded as proven compositionally rather than end to end.
1526
*/
1627

1728
import { describe, it } from "@executablemd/test-support/bdd";

‎packages/workflow/tests/scenarios/IssueDurability.test.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,12 @@ discriminator, the title, the description, the tags and the assignee — so a
3030
changed request diverges at its position rather than answering with the result
3131
retained for a different question.
3232

33-
That claim is about the fingerprint, and it is asserted directly in
34-
`issue-github.test.ts` rather than here. It cannot be staged by running a
35-
*different document* against a retained journal: an edited root is a fork
36-
(§11), and a fork replays the retained expansion positionally rather than
37-
re-reading what the new document says. A scenario written that way would report
38-
the first attempt's URL and look like a passing test of the opposite claim.
33+
That claim is compositional, and it is asserted in `issue-records.test.ts`
34+
rather than here. It stacks three facts: the request fingerprint covers every
35+
member of the request; the durable operation is named by that fingerprint; and a
36+
durable stream diverges when the name at a position is not the one the history
37+
holds there. The first is what those tests vary, one member at a time. The
38+
second is a line at the call site. The third is the stream's own contract.
3939

4040
## What the run retains
4141

0 commit comments

Comments
 (0)