Skip to content

Commit 34b2e11

Browse files
committed
🎫 Create one issue in the tracker a lexical context names
Supersedes this branch's deferred-finding-specific `<Issue>` with the provider-neutral primitive #296 was amended to. An issue provider does not necessarily own a Git repository β€” Atlassian issue tracking owns none β€” so an Atlassian issue could never truthfully execute or persist as a `git_host_effect`. `<Issue>` therefore has a boundary of its own: its own contextual routing operation, `executablemd.workflow.issue`, and its own durable effect type, `issue_effect`. What it reuses from #297 is the observe-before-perform algorithm and the one-surface authority rule, internally. The component is four props β€” `title`, `description`, optional `tags`, optional `assignee` β€” and `as` binds exactly `{ url }`. It renders nothing, so a paired invocation is refused on the shape of the invocation, before the tracker is read and before routing: content this element never renders would be discarded in silence, and an issue created beside text nobody ever saw is worse than one not created at all. Deferral classification, approval, PullRequest provenance, rationale, dependency impact and intended timing are gone from the primitive: they are workflow policy, expressible in document structure or Issue middleware, and folding them in made one team's review process part of the portable contract. Where an issue goes is `<IssueTracker>`, the nearest lexical context, carrying a credential-free URL and an optional provider discriminator. A nested tracker replaces the whole tracker and never merges, because a child inheriting a parent's `provider` while replacing its `url` would ask one service about another's container. The context is composition data: the trusted host installs an adapter-private ceiling beside its credentials, and a target outside it fails before any provider observes anything. A tracker is what a context names; a canonical target URL is the normalized destination inside it, and that is the only place "target" survives β€” durable identity, the natural key and every provider comparison use one spelling of one destination. The table of well-known hosts lives with the host rather than in the shared boundary, and that placement is enforced rather than intended β€” DLC13 refuses a provider's name in the shared coordination surface, and it was right to: the first adapter naming itself in a shared contract is how a neutral boundary quietly becomes one provider's. The shared surface carries the mechanism, the host carries the policy, and `<Issue>` reads the answer through one authority-free resolution. Reconciliation keys `{ canonicalTargetUrl, runId, expansionId }` inside the resolved provider's namespace; the fingerprint covers provider, target, title, description, normalized tags and assignee. Tags are a code-point-sorted set because order is not identity, absence of an assignee has one spelling everywhere, and title is never identity. Retained Issue identities are published beside the run the way Git-host ones are, so a fork adopts its inherited issue rather than filing a second one. Suites need no Workspace, Git or SQLite, and that is the contract rather than an economy: a primitive that reaches a service owning no Git repository must not need one to be tested. Their runtime exclusions are therefore gone. Two test premises were wrong and are corrected rather than worked around: replay does not re-read an edited document β€” that is a fork β€” so the divergence claim is made against the fingerprint directly; and re-entering the shared surface from inside a routing handler recurses, so the forgery attempts are made from outside the finished invocation, where the surface's own default is what answers.
1 parent b8f9033 commit 34b2e11

13 files changed

Lines changed: 174 additions & 89 deletions

File tree

β€Žarchitecture.mdβ€Ž

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ Existing documents and code get aligned to this section retroactively.
3838
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
3939
| 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 |
4040
| 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 target | the credential-free canonical URL naming the container new issues are created in, together with an optional explicit provider discriminator. It is replaceable composition data supplied by lexical context; it requests a destination and grants nothing |
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 |
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 |
4243
| 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 |
4344
| printed error | an error printed into the document (`ErrorSegment`); data, not control flow |
4445
| failure | an error that propagates (`ComponentFailure`, `DocumentationError`) |
@@ -2528,7 +2529,7 @@ Status is measured against main.
25282529
| 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 |
25292530
| `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 |
25302531
| `<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 |
2531-
| `<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 children, no repository/url/provider/token/label/milestone/project/comment/close or approval prop, it renders nothing, and `as` binds exactly `{ url }`. 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 |
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 |
25322533
| 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 |
25332534
| 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 |
25342535
| 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 |

β€Žpackages/workflow/mod.tsβ€Ž

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -214,33 +214,34 @@ export type {
214214
IssueRoutingRequest,
215215
} from "./src/issue/api.ts";
216216
export {
217-
ISSUE_TARGET_CONTEXT,
218-
IssueTargetContext,
219-
currentIssueTarget,
217+
ISSUE_TRACKER_CONTEXT,
218+
IssueTrackerContext,
219+
currentIssueTracker,
220220
} from "./src/issue/context.ts";
221-
export type { IssueTargetContextApi } from "./src/issue/context.ts";
221+
export type { IssueTrackerContextApi } from "./src/issue/context.ts";
222222
export { ISSUE_EFFECT } from "./src/issue/effect-type.ts";
223223
export { reconcileIssueEffect, useIssueProvider, withIssueProvider } from "./src/issue/effect.ts";
224224
export type { IssueEffectRequest } from "./src/issue/effect.ts";
225225
export {
226226
IssueAmbiguousError,
227227
IssueConflictError,
228+
IssueContentError,
228229
IssueProtocolError,
229230
IssueProviderError,
230-
IssueTargetError,
231+
IssueTrackerError,
231232
IssueUnavailableError,
232233
issueFailure,
233234
isIssueRefused,
234235
isIssueUnavailable,
235236
} from "./src/issue/errors.ts";
236-
export type { IssueTargetReason } from "./src/issue/errors.ts";
237+
export type { IssueTrackerReason } from "./src/issue/errors.ts";
237238
export {
238239
canonicalIssueTarget,
239240
issueProviderName,
240241
resolveIssueDestination,
241242
withinIssueCeiling,
242243
} from "./src/issue/target.ts";
243-
export type { IssueDestination, IssueTarget } from "./src/issue/target.ts";
244+
export type { IssueDestination, IssueTracker } from "./src/issue/target.ts";
244245
export {
245246
byCodePoint,
246247
completeIssueRequestJson,

β€Žpackages/workflow/src/composition/components/Issue.tsβ€Ž

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@
33
* names (specs/workflow-workspace-spec.md Β§10.3).
44
*
55
* ```md
6-
* <IssueTarget url={props.tracker}>
6+
* <IssueTracker url={props.tracker}>
77
* <Issue
88
* title="Retry the publish step on a 5xx"
99
* description={finding.evidence}
1010
* tags={["reliability", "publish"]}
1111
* as="issue"
1212
* />
13-
* </IssueTarget>
13+
* </IssueTracker>
1414
*
1515
* Recorded at {issue.url}.
1616
* ```
@@ -25,7 +25,7 @@
2525
*
2626
* Which tracker an issue belongs in is a deployment fact, and a deployment fact
2727
* written into every element is one that cannot be changed without editing
28-
* every element. `<IssueTarget>` says it once for a region; the nearest one
28+
* every element. `<IssueTracker>` says it once for a region; the nearest one
2929
* wins, and a nested one replaces the whole target rather than merging with it.
3030
*
3131
* The context is composition data. It requests a destination and grants
@@ -52,17 +52,18 @@
5252
*
5353
* ## Failure
5454
*
55-
* A missing context, a URL that is not a credential-free container, and a URL
56-
* no built-in mapping names a provider for are decided here, before routing
57-
* exists in the story. What a provider answers β€” a conflict, an ambiguity, an
55+
* Content written around it, a missing context, a URL that is not a
56+
* credential-free container, and a URL the host maps no provider to are decided
57+
* here, before routing exists in the story. What a provider answers β€” a conflict, an ambiguity, an
5858
* unavailability, a target outside the host's ceiling β€” travels under Β§10.3's
5959
* vocabulary.
6060
*/
6161

62+
import { hasContent } from "@executablemd/core";
6263
import type { PropsSchema, ReturnsSchema } from "@executablemd/core";
6364
import type { Operation } from "effection";
6465
import type { Json } from "@executablemd/durable-streams";
65-
import { currentIssueTarget, issueProviderFor } from "../../issue/context.ts";
66+
import { currentIssueTracker, issueProviderFor } from "../../issue/context.ts";
6667
import { resolveIssueDestination } from "../../issue/target.ts";
6768
import { reconcileIssueEffect } from "../../issue/effect.ts";
6869
import {
@@ -72,7 +73,7 @@ import {
7273
parseIssueRecordResult,
7374
type IssueInputs,
7475
} from "../../issue/records.ts";
75-
import { IssueProtocolError } from "../../issue/errors.ts";
76+
import { IssueContentError, IssueProtocolError } from "../../issue/errors.ts";
7677

7778
/** The component name, as a document writes it and as a refusal names it. */
7879
export const ISSUE_ELEMENT = "<Issue>";
@@ -120,10 +121,21 @@ export const returns: ReturnsSchema = {
120121
};
121122

122123
export default function* Issue(props: Record<string, Json>): Operation<Json> {
123-
// The destination first, and locally. A document that named no container, or
124+
// Before the destination is resolved, before routing and before any provider
125+
// is asked anything. This element renders nothing, so content written around
126+
// it would be discarded in silence β€” and an issue created beside text nobody
127+
// ever saw is worse than one not created at all.
128+
if (yield* hasContent()) {
129+
throw new IssueContentError(
130+
`${ISSUE_ELEMENT} renders nothing, so it takes no content. The issue's text is its ` +
131+
`description prop. Write it as <Issue title=… description=… as=… />.`,
132+
);
133+
}
134+
135+
// The destination next, and locally. A document that named no container, or
124136
// one nothing can resolve a provider for, is refused before an effect
125137
// identity exists and before any surface has been asked anything.
126-
const target = yield* currentIssueTarget();
138+
const target = yield* currentIssueTracker();
127139
// The mapping is the host's, read here and applied by the shared resolution
128140
// so that one place decides what a destination is.
129141
const resolved = target === undefined ? undefined : yield* issueProviderFor(target.url);

packages/workflow/src/composition/components/IssueTarget.ts renamed to packages/workflow/src/composition/components/IssueTracker.ts

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
/**
2-
* `<IssueTarget>` β€” which tracker or project the issues inside it belong in
2+
* `<IssueTracker>` β€” which tracker or project the issues inside it belong in
33
* (specs/workflow-workspace-spec.md Β§10.3).
44
*
55
* ```md
6-
* <IssueTarget url={props.tracker}>
6+
* <IssueTracker url={props.tracker}>
77
* <Issue title="Retry the publish step" description={finding.evidence} as="issue" />
8-
* </IssueTarget>
8+
* </IssueTracker>
99
* ```
1010
*
1111
* `url` is a credential-free URL naming the container new issues are created
@@ -36,11 +36,11 @@ import { content, hasContent } from "@executablemd/core";
3636
import type { PropsSchema } from "@executablemd/core";
3737
import type { Operation } from "effection";
3838
import type { Json } from "@executablemd/durable-streams";
39-
import { IssueTargetContext } from "../../issue/context.ts";
40-
import type { IssueTarget as Target } from "../../issue/target.ts";
39+
import { IssueTrackerContext } from "../../issue/context.ts";
40+
import type { IssueTracker as Tracker } from "../../issue/target.ts";
4141

4242
/** The component name, as a document writes it and as a refusal names it. */
43-
export const ISSUE_TARGET_ELEMENT = "<IssueTarget>";
43+
export const ISSUE_TRACKER_ELEMENT = "<IssueTracker>";
4444

4545
export const props: PropsSchema = {
4646
type: "object",
@@ -59,11 +59,11 @@ export const props: PropsSchema = {
5959
additionalProperties: false,
6060
};
6161

62-
export default function* IssueTarget(props: Record<string, Json>): Operation<string> {
62+
export default function* IssueTracker(props: Record<string, Json>): Operation<string> {
6363
if (!(yield* hasContent())) {
6464
return "";
6565
}
66-
const target: Target = Object.freeze({
66+
const tracker: Tracker = Object.freeze({
6767
url: typeof props.url === "string" ? props.url : "",
6868
// Absent rather than empty: the whole point of the discriminator is that
6969
// stating one and stating nothing are different requests, and an empty
@@ -72,6 +72,6 @@ export default function* IssueTarget(props: Record<string, Json>): Operation<str
7272
? { provider: props.provider }
7373
: {}),
7474
});
75-
yield* IssueTargetContext.around({ current: () => target }, { at: "min" });
75+
yield* IssueTrackerContext.around({ current: () => tracker }, { at: "min" });
7676
return yield* content();
7777
}

β€Žpackages/workflow/src/composition/installation.tsβ€Ž

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* Registers the composition components as ordinary defaults.
33
*
4-
* Repository, Worktree, Dir, the Git operations, PullRequest, IssueTarget and
4+
* Repository, Worktree, Dir, the Git operations, PullRequest, IssueTracker and
55
* Issue are ordinary
66
* registered defaults β€” not reserved and not structural β€” so a repository-local component
77
* may shadow one for its own scope, and the workflow host installs them only
@@ -27,7 +27,7 @@ import PullRequest, {
2727
returns as pullRequestReturns,
2828
} from "./components/PullRequest.ts";
2929
import Issue, { props as issueProps, returns as issueReturns } from "./components/Issue.ts";
30-
import IssueTarget, { props as issueTargetProps } from "./components/IssueTarget.ts";
30+
import IssueTracker, { props as issueTrackerProps } from "./components/IssueTracker.ts";
3131

3232
const ORIGIN = "@executablemd/workflow/composition";
3333

@@ -84,10 +84,10 @@ export function useCompositionComponents(): Operation<void> {
8484
fn: PullRequest,
8585
},
8686
{
87-
name: "IssueTarget",
87+
name: "IssueTracker",
8888
origin: ORIGIN,
89-
props: issueTargetProps,
90-
fn: IssueTarget,
89+
props: issueTrackerProps,
90+
fn: IssueTracker,
9191
},
9292
{
9393
name: "Issue",

β€Žpackages/workflow/src/deno/issue/provider.tsβ€Ž

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
import type { Operation } from "effection";
1818
import { useIssueProvider } from "../../issue/effect.ts";
19-
import { IssueTargetContext } from "../../issue/context.ts";
19+
import { IssueTrackerContext } from "../../issue/context.ts";
2020
import { builtInIssueProvider } from "./resolution.ts";
2121
import type { IssueProvider } from "../../issue/api.ts";
2222
import type { GitHubAccess } from "../composition/github.ts";
@@ -55,7 +55,7 @@ export function* useIssueProviders(options: IssueProviderOptions = {}): Operatio
5555
// Beside the adapters, because the table of well-known hosts is host policy.
5656
// It answers the resolution alone and leaves the target a context supplies to
5757
// whatever installed one further in.
58-
yield* IssueTargetContext.around(
58+
yield* IssueTrackerContext.around(
5959
{
6060
// deno-lint-ignore require-yield
6161
*resolve([target]): Operation<string | undefined> {

β€Žpackages/workflow/src/deno/issue/resolution.tsβ€Ž

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Which provider a canonical Issue target selects when a context named none.
2+
* Which provider a canonical target URL selects when a tracker named no provider.
33
*
44
* The table lives with the trusted host rather than in the shared boundary, and
55
* that placement is enforced: the shared coordination surface may not name a

0 commit comments

Comments
Β (0)