Skip to content

Commit 17efce0

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 a3249d1 commit 17efce0

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
@@ -1004,31 +1004,6 @@ performs a proven absence exactly once, and refuses conflict and permanent
10041004
ambiguity. A Git host need not implement every kind; one that does not refuses
10051005
from observation, before any remote work.
10061006

1007-
Issue creation is a boundary of its own, and that separation is the point rather
1008-
than an accident of layering. An Issue provider does not necessarily own a Git
1009-
repository — Atlassian issue tracking owns none — so an Atlassian issue could
1010-
not truthfully execute or persist as a Git-host effect. `<Issue>` therefore has
1011-
its own contextual routing operation and its own durable effect type,
1012-
`issue_effect`, and reuses the reconciliation mechanics above internally rather
1013-
than by sharing the Git-host boundary. What is Issue-owned, and therefore an
1014-
Issue compatibility boundary, is the stable API name, the normalized request,
1015-
the provider identity, the natural key, the result and the durable effect type.
1016-
1017-
Which external system an issue is requested in is lexical context, and whether
1018-
that target is authorized is the provider's. The nearest tracker supplies a
1019-
canonical target URL and an optional provider discriminator; the adapter-private
1020-
ceiling installed beside the credential decides whether that target may be
1021-
reached at all. A tracker narrows within the ceiling and can never widen it,
1022-
which is what keeps a replaceable context from being a grant.
1023-
1024-
A provider is ordinary middleware around one operation rather than an entry in a
1025-
registry, and that is the whole mechanism: there is no resolver to consult, no
1026-
phase protocol to speak and no terminal to reach. What the boundary keeps for
1027-
itself is small — it derives the idempotency key, wraps one call durably, and
1028-
retains the URL. Everything about what a particular service can prove, including
1029-
not creating an issue twice, is the middleware's, because that knowledge cannot
1030-
be written once for services that do not agree on what an issue is.
1031-
10321007
Reconciliation is reached through exactly one stable contextual operation, and
10331008
that is a deliberate correction rather than a simplification. An earlier design
10341009
selected a provider on one surface and coordinated the invocation on a second;
@@ -1109,6 +1084,54 @@ without a Git host ever being asked. Fail-stop rather than a bare refusal,
11091084
because a live operation that appended nothing would leave the next one to
11101085
append at its position.
11111086

1087+
Issue creation is a separate boundary, and not that one. Everything above is the
1088+
Git-host contract: a shared state machine, one request-only surface, phases, and
1089+
a private terminal that is the only thing able to author an outcome. `<Issue>`
1090+
has none of it, and none of it is missing.
1091+
1092+
An Issue provider does not necessarily own a Git repository — Atlassian issue
1093+
tracking owns none — so an Atlassian issue could not truthfully execute or
1094+
persist as a Git-host effect. `<Issue>` therefore reaches its own stable
1095+
contextual operation, `executablemd.workflow.issue`, whose only member is
1096+
`upsert(issue, options)`, and journals its own durable effect type,
1097+
`issue_effect`. What is Issue-owned, and therefore an Issue compatibility
1098+
boundary, is that API name, the normalized request, the idempotency key, the
1099+
result and the effect type.
1100+
1101+
The difference is not only which name is called. A Git-host provider is selected
1102+
by the reconciliation and answers through a terminal it cannot address directly,
1103+
because the state machine is shared and the journal may hold only what that
1104+
terminal accepted. An Issue provider is ordinary middleware: it composes
1105+
`IssueApi.around(...)`, reads the destination it was handed, and either handles
1106+
the request or delegates it untouched. There is no registry, no resolver, no
1107+
phase protocol and no terminal. What would have been the state machine's job is
1108+
the middleware's instead, because knowing whether an issue already exists is
1109+
knowledge about one service rather than about external effects in general, and a
1110+
shared machine would have to be told it by every adapter that disagreed.
1111+
1112+
So the Issue boundary keeps little for itself: it derives an idempotency key
1113+
from the canonical target and the run's own effect identity, wraps one call
1114+
durably, validates that what came back is a URL and nothing else, and retains
1115+
it. Replay answers from the journal without calling the operation at all. What
1116+
it does not promise is that the service was touched once — observing before
1117+
mutating, adopting a compatible issue, creating once, recovering an interrupted
1118+
creation and refusing conflict and ambiguity all belong to the middleware, and
1119+
the key is what this side hands over so the middleware can make it true.
1120+
1121+
Which external system an issue is requested in is lexical context, and whether
1122+
that target is authorized is the provider's. The nearest tracker supplies a
1123+
canonical target URL and an optional provider discriminator; the adapter-private
1124+
ceiling installed beside the credential decides whether that target may be
1125+
reached at all. A tracker narrows within the ceiling and can never widen it,
1126+
which is what keeps a replaceable context from being a grant.
1127+
1128+
Without a discriminator each provider matches its own URLs; with one, only the
1129+
provider of that name may act, which is how a self-hosted deployment is
1130+
addressed. Once middleware matches it owns the answer: it never delegates
1131+
afterwards, and nothing catches its refusal to try somebody else, because a
1132+
search is how a document that named one service quietly reaches another. A
1133+
destination every provider delegated reaches the operation's own base error.
1134+
11121135
Every committed journal event references the current logical Workspace root.
11131136
Only committed event boundaries are checkpoints. A history fork copies the
11141137
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)