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 cd53e51
Browse filesBrowse the repository at this point in the historyBrowse files
🎫 Create one issue in the container 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.
#297's Git-host boundary goes back to owning Push and PullRequest only.
The component is four props — `title`, `description`, optional `tags`, optional
`assignee` — no children, and `as` binds exactly `{ url }`. Deferral
classification, approval, PullRequest provenance, rationale, dependency impact
and intended timing are gone from it: 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 `<IssueTarget>`, the nearest lexical context, carrying a
credential-free URL and an optional provider discriminator. A nested target
replaces the whole target 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.
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.
Copy file name to clipboardExpand all lines: architecture.md
+31-11Lines changed: 31 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,7 +36,10 @@ Existing documents and code get aligned to this section retroactively.
36
36
| expansion | one logical evaluation of an authored executable element within a document execution |
37
37
| expansion ID | a deterministic identifier for one logical expansion; restoring or retrying that expansion preserves the ID, while a distinct evaluation requested by the document receives another |
38
38
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
39
-
| Git host | an external service that owns remote Git repositories and associated collaboration objects such as branches, pull requests, and issues. GitHub is one Git-host adapter. A Git host is distinct from the local Git capability and the trusted workflow host |
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
+
| 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 |
42
+
| 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 |
40
43
| printed error | an error printed into the document (`ErrorSegment`); data, not control flow |
41
44
| failure | an error that propagates (`ComponentFailure`, `DocumentationError`) |
42
45
| 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) |
@@ -991,14 +994,31 @@ absence and refuses conflicting or permanently ambiguous state. Temporary
991
994
provider unavailability may be retried or suspended by explicit middleware; it
992
995
never authorizes a duplicate effect while completion is unknown.
one provider-neutral reconciliation of that boundary, so a new Git-host effect
996
-
kind supplies a request and a provider rather than a replay policy of its own.
997
-
Prompt is not one of them: it keeps its own Agent-provider contract. A live
998
-
Git-host attempt observes before it mutates, adopts a proven compatible
999
-
completion, performs a proven absence exactly once, and refuses conflict and
1000
-
permanent ambiguity. A Git host need not implement every kind; one that does not
1001
-
refuses from observation, before any remote work.
997
+
Git-host mutations — Git push and pull-request upsert — share one
998
+
provider-neutral reconciliation of that boundary, so a new Git-host effect kind
999
+
supplies a request and a provider rather than a replay policy of its own. Prompt
1000
+
is not one of them: it keeps its own Agent-provider contract. A live Git-host
1001
+
attempt observes before it mutates, adopts a proven compatible completion,
1002
+
performs a proven absence exactly once, and refuses conflict and permanent
1003
+
ambiguity. A Git host need not implement every kind; one that does not refuses
1004
+
from observation, before any remote work.
1005
+
1006
+
Issue creation is a boundary of its own, and that separation is the point rather
1007
+
than an accident of layering. An Issue provider does not necessarily own a Git
1008
+
repository — Atlassian issue tracking owns none — so an Atlassian issue could
1009
+
not truthfully execute or persist as a Git-host effect. `<Issue>` therefore has
1010
+
its own contextual routing operation and its own durable effect type,
1011
+
`issue_effect`, and reuses the reconciliation mechanics above internally rather
1012
+
than by sharing the Git-host boundary. What is Issue-owned, and therefore an
1013
+
Issue compatibility boundary, is the stable API name, the normalized request,
1014
+
the provider identity, the natural key, the result and the durable effect type.
1015
+
1016
+
Which external system an issue is requested in is lexical context, and whether
1017
+
that target is authorized is the trusted host's. The nearest Issue context
1018
+
supplies a canonical target URL and an optional provider discriminator; the
1019
+
host's private ceiling decides whether that target may be reached at all.
1020
+
Context and routing middleware select and narrow within the ceiling and can
1021
+
never widen it, which is what keeps a replaceable context from being a grant.
1002
1022
1003
1023
Reconciliation is reached through exactly one stable contextual operation, and
1004
1024
that is a deliberate correction rather than a simplification. An earlier design
@@ -2432,7 +2452,7 @@ Status is measured against main.
2432
2452
| caller-owned storage transaction | publishes several changes, including journal events, in one transaction nothing else enlists in | built on main |
2433
2453
| live durable-operation coordinator | explicitly coordinates structured live execution with existing Yield publication while leaving replay and callback effects unchanged | built on the #365 stack |
2434
2454
| Workspace coordination API | fails closed by default; replaceable context routes only a one-use provider selection, while the selected provider directly invokes an execution-owned credentialed capability for execution, publication and failure activation | built on the #365 stack; the Deno provider installs an adapter-private atomic handler |
2435
-
| shared Git-host reconciliation | reconciles Git push, pull-request upsert and issue creation through one provider-neutral state machine journaled as `git_host_effect` — Prompt is not a consumer and keeps its own Agent-provider contract: run and expansion identity derived by the engine, observation before mutation, adoption of a proven compatible completion, one performance of a proven absence, refusal of conflict and permanent ambiguity, temporary unavailability as its own ordinary failure, and a provider free to support only some kinds; routing is one request-only contextual operation carrying no completion authority, and only an answer the invocation's own terminal accepted can author a journaled outcome | built on the #297 stack; `Git.Push` is its first consumer, built on the #370 stack, and `<PullRequest>` its second — a create-or-update upsert — built on the #295 stack, while the issue component remains unbuilt (#296) |
2455
+
| shared Git-host reconciliation | reconciles Git push and pull-request upsert through one provider-neutral state machine journaled as `git_host_effect` — Prompt is not a consumer and keeps its own Agent-provider contract: run and expansion identity derived by the engine, observation before mutation, adoption of a proven compatible completion, one performance of a proven absence, refusal of conflict and permanent ambiguity, temporary unavailability as its own ordinary failure, and a provider free to support only some kinds; routing is one request-only contextual operation carrying no completion authority, and only an answer the invocation's own terminal accepted can author a journaled outcome | built on the #297 stack; `Git.Push` is its first consumer, built on the #370 stack, and `<PullRequest>` its second — a create-or-update upsert — built on the #295 stack. `<Issue>` reuses these mechanics inside a boundary of its own rather than joining this one (#296) |
2436
2456
| explicit WorkflowRun journal route | binds one already-filtered publication to one exact active transaction and otherwise uses ordinary serialized journal storage | built on the #365 stack |
2437
2457
|`API.Service` / `startService()`| creates an authenticated, supervised loopback service attachment through a provider-neutral operation | built on main |
2438
2458
| foreground command routing and retention | forwards a child's channels live, captures stdout for a `<Capture as>` region, and retains output only when the host asked for a record | built on the #441 stack |
@@ -2452,7 +2472,7 @@ Status is measured against main.
2452
2472
| 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 |
2453
2473
|`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 |
2454
2474
| `<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 |
2455
-
| `<Issue>` | records one approved deferred obligation as a Git-host issue in the same Repository as the retained PullRequest evidence it names: required `finding`, `disposition`, `pullRequest`, `title`, `rationale`, `dependencyImpact` and `intendedTiming`, rendered content as evidence, no repository/provider/token/label/assignee/milestone/project/comment/close controls, and no implicit pull-request behavior. Only `defer` reaches a durable suspension request whose body is the exact normalized Issue request; `{ approved: false }`, `rejected`, `fix-now` and `inserted-repair` create no issue and observe no provider, while `{ approved: true }` authorizes only that request. A successful `PullRequest` result from the same run is admitted before Git-host observation. Reconciliation keys the Repository identity, PullRequest provider identity and finding ID; it creates once, adopts or updates one compatible open issue, and refuses closed, multiple or conflicting matches rather than overwriting. Its `as` value is stable issue evidence — filtered Repository identity, PullRequest number and URL, provider issue identity, issue number, URL, state `open`, finding ID and decision — not a live issue snapshot; the first adapter works over `github.com`, writes one origin marker in the issue body, uses `GH_TOKEN` then `GITHUB_TOKEN`, and confines endpoint, credential and raw payloads to the per-invocation provider closure | built on the #296 stack, Deno provider only |
2475
+
| `<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 |
2456
2476
| workflow lifecycle inspection and control | reads status/list/history without advancing a run, enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | built on the #367 stack |
2457
2477
| 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 |
2458
2478
| 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