You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9be075d
Browse filesBrowse the repository at this point in the historyBrowse files
🎫 Upsert one issue through middleware the tracker selects
Replaces the Issue routing surface with one operation and ordinary middleware,
per the amended #296 contract.
`IssueApi` now exposes only `upsert(issue, options)`. There is no registry, no
resolver, no routing protocol, no phase API and no private terminal: a provider
is `IssueApi.around(...)` middleware that looks at the destination it was handed
and either handles the request or delegates it untouched. Without a
discriminator a provider matches its own URLs; with one, only the provider of
that name may act — which is why a provider now validates a URL by its path
shape rather than by its host once it has been named outright, so an explicit
`github` reaches the GitHub middleware for a self-hosted deployment.
Once middleware matches it owns the answer. It never delegates afterwards, and
nothing catches its refusal to try somebody else, because a search is how a
document that named one service quietly reaches another. A destination everyone
delegated reaches `NoIssueProvider` unchanged, naming the URL and the
discriminator the document wrote.
`issue_effect` is now a thin envelope: it derives the idempotency key from the
canonical target and the run's own effect identity, wraps one `upsert()` call
durably, validates that what came back is a URL and nothing else, and retains
it. Replay returns that URL without invoking `IssueApi` at all. What the
envelope does not promise is that the *service* was touched once — that is the
provider's, and the key is what this side hands over so the provider can make it
true.
Observing, adopting, creating once, updating and recovering an interrupted
creation therefore all moved inside the GitHub middleware, where they belong:
they are knowledge about what a particular service can prove, and they cannot be
written once for services that do not agree on what an issue is.
The evidence moved with the contract. Four checked-in documents under
`tests/scenarios/` state it in Markdown — props and result, tracker validation,
tag and assignee normalization, nesting, URL and discriminator matching, a
matched refusal being final, the base error, the ceiling, replay, recovery and
what the journal may hold. They use `<Test>` and assertions and contain no eval
blocks. `issue-markdown.test.ts` reads them from disk and reports each `<Test>`;
`issue-github.test.ts` keeps only what a document cannot construct — payload
reading, target parsing, canonicalization and durable identity. `issue.test.ts`
and `issue-durability.test.ts` are gone rather than duplicated.
Two things the frozen matrix asked for are not staged the way it described, and
both are recorded where a reader meets them:
D1 cannot be shown by offering a first attempt's history to a document that
changed one field. An edited root is a fork, not a resume, and a fork replays the
retained expansion positionally rather than re-reading the new document — a
scenario written that way reports the first attempt's URL and looks like a
passing test of the opposite claim. The fingerprint claim is asserted directly
instead, over every member of the request, and `IssueDurability.test.md` says why
it lives there.
The `user:password` spelling of a credentialed target URL is not written in
`Issue.test.md`: this repository's secret gate reads a document before it is
journaled and refuses a literal of that shape, so the scenario uses the userinfo
form the canonicalizer refuses for the same reason.
Copy file name to clipboardExpand all lines: architecture.md
+16-8Lines changed: 16 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,9 +38,9 @@ Existing documents and code get aligned to this section retroactively.
38
38
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
39
39
| Git host | an external service that owns remote Git repositories and associated collaboration objects such as branches and pull requests. GitHub is one Git-host adapter. A Git host is distinct from the local Git capability and the trusted workflow host, and from an Issue provider |
40
40
| Issue provider | an external service that owns a collection of issues. GitHub and Atlassian Cloud are Issue-provider adapters. It is a separate boundary from a Git host because an Issue provider need not own a Git repository, and one that does not cannot truthfully persist as a Git-host effect |
41
-
| Issue tracker | what a lexical Issue context names: a credential-free URL for the container new issues are created in, together with an optional explicit provider discriminator. It is replaceable composition data; it requests a destination and grants nothing |
41
+
| Issue tracker | what a lexical `<IssueTracker>` names: a credential-free URL for the container new issues are created in, together with an optional explicit provider discriminator. It is replaceable composition data; it requests a destination and grants nothing |
42
42
| canonical target URL | the normalized form of an Issue tracker's URL. One destination has one spelling, which is what durable identity, the natural key and every provider comparison use |
43
-
| provider discriminator | the stable lower-case name of an Issue provider. It selects which installed provider may accept a request, and is resolved from the canonical target URL when the context does not state one|
43
+
| provider discriminator | the stable lower-case name of an Issue provider. Stated on a tracker, it names the only provider allowed to handle the request; omitted, each installed provider matches the URLs it recognizes|
44
44
| printed error | an error printed into the document (`ErrorSegment`); data, not control flow |
45
45
| failure | an error that propagates (`ComponentFailure`, `DocumentationError`) |
46
46
| 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) |
@@ -1069,11 +1069,19 @@ Issue compatibility boundary, is the stable API name, the normalized request,
1069
1069
the provider identity, the natural key, the result and the durable effect type.
1070
1070
1071
1071
Which external system an issue is requested in is lexical context, and whether
1072
-
that target is authorized is the trusted host's. The nearest Issue context
1073
-
supplies a canonical target URL and an optional provider discriminator; the
1074
-
host's private ceiling decides whether that target may be reached at all.
1075
-
Context and routing middleware select and narrow within the ceiling and can
1076
-
never widen it, which is what keeps a replaceable context from being a grant.
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.
1077
1085
1078
1086
Reconciliation is reached through exactly one stable contextual operation, and
1079
1087
that is a deliberate correction rather than a simplification. An earlier design
@@ -2529,7 +2537,7 @@ Status is measured against main.
2529
2537
| 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 |
2530
2538
|`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 |
2531
2539
| `<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`, 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 |
2532
-
| `<Issue>` | creates one issue in the container the nearest lexical Issue context names, through a boundary of its own rather than the Git host's: exactly `title`, `description`, optional `tags` and optional `assignee`, no repository/url/provider/token/label/milestone/project/comment/close or approval prop, it renders nothing, and `as` binds exactly `{ url }`. A paired invocation is refused on the shape of the invocation, before the tracker is read and before routing. The context carries a credential-free `url` and an optional `provider`; the URL is canonicalized and the provider resolved from a table of well-known hosts the trusted host installs beside its adapters — `github.com` to `github`, `*.atlassian.net` to `atlassian` — so the shared boundary carries the mechanism and never a provider's name, unless the context states one, which wins and never falls back on refusal. A nested context replaces the whole target for its descendants and members are never merged. The context is composition data, not authority: the trusted host installs an adapter-private target ceiling beside its credentials, and a target outside it fails before external observation. Routing is one request-only contextual operation, `executablemd.workflow.issue`, under #297's one-surface authority rule. Identity is engine-derived; the natural key is `{ canonicalTargetUrl, runId, expansionId }` within the resolved provider's namespace and the fingerprint covers provider, canonical URL, title, description, normalized tags and assignee. Tags are deduplicated and code-point sorted because order is not identity, and title is never identity. Reconciliation is journaled as `issue_effect`, retaining the normalized request, provider name, pre-state, observations, decision and normalized result — no credential, payload, endpoint or host path. Deferral classification, approval and PullRequest provenance are workflow policy expressed in document structure or Issue middleware, not members of this primitive | built on the #296 stack; GitHub adapter, Deno host |
2540
+
| `<Issue>` | creates one issue in the container the nearest lexical `<IssueTracker>` names, through a boundary of its own rather than the Git host's: exactly `title`, `description`, optional `tags` and optional `assignee`, no repository/url/provider/token/label/milestone/project/comment/close or approval prop, it renders nothing, and `as` binds exactly `{ url }`. A paired invocation is refused on the shape of the invocation, before the tracker is read. 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. It is composition data, not authority: the provider holds an adapter-private ceiling beside its credentials, and a target outside it fails before anything is sent. Upsert is one stable contextual operation, `executablemd.workflow.issue`, with the single member `upsert(issue, options)`; a provider is ordinary middleware around it, matching its own URLs without a discriminator and only its own name with one. Once middleware matches it owns the answer — it never delegates afterwards, and nothing catches its refusal to try somebody else — and a destination everyone delegated reaches `NoIssueProvider` unchanged. `issue_effect` derives the idempotency key from the canonical target and the run's own effect identity, durably wraps the one call, and retains the request and the URL — no credential, payload, endpoint, provider identity or host path. 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 | built on the #296 stack; GitHub middleware, Deno host |
2533
2541
| 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 |
2534
2542
| 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 |
2535
2543
| history fork | creates a new run from one compatible checkpoint and retained Workspace root, under a new immutable definition and normalized props | built on the #368 stack, Deno provider only |
0 commit comments