Skip to content

Commit 5d53e27

Browse files
committed
✨ Give an ordinary xmd run the repository vocabulary, root and nested (#643)
The provider exists; this is everything that reaches it. The Deno source entrypoint and the compiled binary install it for `xmd run` and for an approved `xmd plan --run`, parameterized by the same credential-helper assembly the workflow host uses and by the two existing host configurations, both read and validated before a document expands rather than in the middle of one. Node and Bun register the same thirteen declarations and install no operational provider, so `xmd syntax` describes one language everywhere and every repository operation there reaches a clear provider-absence error before a lock, a credential, a subprocess or a request exists. One array, declared once, with three consumers: the workflow attachment, `xmd syntax` and `xmd plan`, and an ordinary document execution. `run-repositories.ts` names the managed root and the unsupported installer and sits on the shared command path; `deno-repositories.ts` assembles the live provider and is imported only by the two Deno entrypoints. That split is load bearing rather than tidy: the adapter's module graph reaches `node:sqlite`, which Bun has no built-in for, so a static import from shared code would stop `xmd` loading on Bun entirely instead of refusing one operation. A nested `<Execution host="run">` child is an ordinary run whatever command hosts it, and gets what one gets: a provider instance of its own — its own invocation identity, leases and Push evidence — and the working directory the `<Execution>` was written in. Those two are one thing. A child is a root execution in a scope that does not descend from the document's, so it inherits no `API.Env` handler and would otherwise stand in the *process* directory: a `<Dir>` would scope every component inside it except the child, and the child's own provider would discover its ambient Git from whatever checkout the process happened to be launched in. Authority without placement is worse than neither, so the contextual directory is captured on the last line still inside the invocation, carried privately on `ChildInvocation`, and installed ahead of the root, the provider and the execution. Evidence: ORC1–ORC19 and ORC21, the retained workflow regression, the compiled smoke, and portable parity under Node and Bun.
1 parent dda8c84 commit 5d53e27

14 files changed

Lines changed: 668 additions & 8 deletions

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3785,7 +3785,7 @@ Status is measured against main.
37853785
| `Git.Push` under an ordinary run | keeps the same observe/adopt/fast-forward/refuse rules and the same isolated transport aimed at the checkout's admitted `origin`: a destination proven absent is published once, one already naming this exact commit is adopted, one holding a proven ancestor is published over by the same exact non-force refspec, and a divergent or unreadable one is a conflict, with an unreachable host never read as absence. It reconciles no Git-host effect and retains nothing. After a verified performed or adopted publication it stores one private evidence entry — the authenticated Repository identity, canonical checkout root, origin, named branch, destination ref and exact commit — in the provider instance's own closure. A checkout with no admitted `origin` refuses before a credential, a session or a transport exists | built on the #643 stack, Deno and compiled only |
37863786
| `<PullRequest>` and its evidence reads under an ordinary run | share the URL matching, host ceiling, response normalization and low-level GitHub reconciliation, and differ in lifecycle and authority. A read is performed afresh every execution and retained nowhere. An upsert authenticates the Repository selection and the contextual checkout, reads the current named branch and commit, and requires the exact matching entry this provider instance already holds — a Push for another checkout, Repository, origin, destination, branch or commit is irrelevant, a later Push of the same destination supersedes the earlier entry, and missing or conflicting evidence is a local refusal before a credential is opened. Nothing crosses executions: a new run and a new `--journal` run each start with a new invocation identity and empty evidence, and copying a Context value, a component result or a previous trace file grants nothing. Within one invocation the attempt happens at most once; across a process interruption there is no exactly-once claim | built on the #643 stack, Deno and compiled only |
37873787
| `<Issue>` under an ordinary run | reaches the same configured transport under the same host ceiling, with no durable envelope: identity is this execution's own opaque invocation identity together with the engine's expansion identity, so an upsert presents an idempotency key a provider can carry and a second run is a new request rather than a resumption. Absent or out-of-ceiling configuration installs no matching provider and sends no credential and no request | built on the #643 stack, Deno and compiled only |
3788-
| ordinary repository provider assembly | the Deno source entrypoint and the compiled binary install the live provider for `xmd run` and for an approved `xmd plan --run`, parameterized by the same credential-helper assembly the workflow host uses and by the two existing host configurations, `XMD_WORKFLOW_GITHUB_ISSUES` and `XMD_WORKFLOW_GITHUB_PULL_REQUESTS`, both read and validated before a document runs. The outer `xmd test` command, a nested `<Execution host="run">` child and a workflow execution install none. Node and Bun register the vocabulary and install no operational provider, so every repository operation reports an absent provider before a lock, a credential, a subprocess or a request exists | built on the #643 stack |
3788+
| ordinary repository provider assembly | the Deno source entrypoint and the compiled binary install the live provider for `xmd run` and for an approved `xmd plan --run`, parameterized by the same credential-helper assembly the workflow host uses and by the two existing host configurations, `XMD_WORKFLOW_GITHUB_ISSUES` and `XMD_WORKFLOW_GITHUB_PULL_REQUESTS`, both read and validated before a document runs. A nested `<Execution host="run">` child receives a fresh instance — its own invocation identity, leases and Push evidence — so nothing it publishes authorizes its parent or a sibling. The outer `xmd test` command and a workflow execution install none. Node and Bun register the vocabulary and install no operational provider, so every repository operation reports an absent provider before a lock, a credential, a subprocess or a request exists | built on the #643 stack |
37893789
| `<Issue>` under a workflow run | asks one of two questions, decided by its own shape, through a boundary of its own rather than the Git host's. Self-closing with `url` reads that issue and binds `{ url, title, description, tags, assignee }`; paired with `title` upserts and binds exactly `{ url }`, its rendered content being the description. There is no `description` prop. Props are exactly `url`, `title`, optional `tags`, optional `assignee` and — on a read only — optional `provider`; no repository/token/label/milestone/project/comment/close or approval prop. Both forms render nothing. The form is decided before the tracker is read, before any provider is asked and before an `issue_effect` record exists, and that is where a mixed `url`+`title`, a read carrying content or `tags`/`assignee`, an upsert with no content, an upsert naming a `provider`, and an element that is neither are all refused. A read needs no tracker — its URL is the identity; an upsert requires the nearest lexical `<IssueTracker>` and takes its discriminator only from there. 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, with the enclosing one restored on leaving. It is composition data, not authority: the provider holds an adapter-private ceiling beside its credentials, admitted before it connects, so a target outside it sends nothing. One stable contextual operation, `executablemd.workflow.issue`, with `read(url, options)` and `upsert(issue, options)`; a provider is ordinary middleware around it, matching its own URLs without a discriminator and only its own name with one, independently per member, with no host-side resolution. Once middleware matches it owns the answer — it never delegates afterwards, and nothing catches its refusal to try somebody else — and a request everyone delegated reaches `NoIssueProvider` unchanged. `issue_effect` records an operation discriminator with the normalized request and result; both forms replay without reaching `IssueApi` and therefore without network access; only an upsert derives an idempotency key, from the operation, the canonical target and the run's own effect identity. Retention excludes credentials, endpoints, payloads, provider identities, origin markers and host paths. 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. The Deno workflow host installs configured GitHub middleware and installs none otherwise, so absence of configuration is fail-closed | built on the #296 stack; GitHub middleware, Deno host |
37903790
| 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 |
37913791
| XMD artifact export, inspection and fork source | seals one run's committed retained state, Workspace roots and workflow definition source closure into one immutable `.xmd` evidence file; opens that file read-only for status/history and admits continuation only by creating a new history fork whose lineage names the artifact identity | specified by `specs/xmd-artifact-spec.md`; the version-1 sealed container, its total read-only verifier, `xmd workflow export` and artifact `status`/`history` are built, Deno provider only — the artifact-source fork remains unbuilt. Inspection is two sibling lifecycle operations, `inspectArtifact()` and `historyArtifact()`, taking a path rather than a run id: a run id names live lifecycle authority and a path names immutable evidence, so neither is a mode of the other. They reach no run store, lock, Workspace, definition reader or external provider, and the artifact path never enters the structural answer |

‎packages/cli/src/cli.ts‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -923,6 +923,7 @@ function* runDocument(
923923
mode: DocumentMode,
924924
installService: HostServiceInstaller,
925925
installRepositories: RepositoryInstaller,
926+
childRepositories: RepositoryInstaller,
926927
): Operation<Result<void>> {
927928
const { root, include, verbose, journal, raw, secretDetection, retainProcessOutput } = config;
928929

@@ -1052,6 +1053,13 @@ function* runDocument(
10521053
includes: include,
10531054
secretDetection,
10541055
installService,
1056+
// The *entrypoint's* installer, not this command's. A `host="run"` child is
1057+
// an ordinary run whatever command is hosting it, so `xmd test` — which
1058+
// installs no repository provider for its own document — still gives one to
1059+
// a child that asked to be a run. Passed rather than inherited because a
1060+
// child runs in an isolated scope and needs a fresh instance: its own
1061+
// invocation identity, its own leases and its own Push evidence.
1062+
installRepositories: childRepositories,
10551063
testAgentWorker: yield* readWorkerCommand(),
10561064
plan,
10571065
});
@@ -1154,9 +1162,12 @@ function* runScopedDocument(
11541162
mode: DocumentMode,
11551163
installService: HostServiceInstaller,
11561164
installRepositories: RepositoryInstaller,
1165+
childRepositories: RepositoryInstaller = installRepositories,
11571166
): Operation<Result<void>> {
11581167
try {
1159-
return yield* scoped(() => runDocument(config, mode, installService, installRepositories));
1168+
return yield* scoped(() =>
1169+
runDocument(config, mode, installService, installRepositories, childRepositories),
1170+
);
11601171
} catch (error) {
11611172
return Err(error instanceof Error ? error : new Error(String(error)));
11621173
}
@@ -1306,10 +1317,12 @@ function* test(
13061317
{ ...config, root: { path } },
13071318
{ testing: true },
13081319
installService,
1309-
// `xmd test` installs no operational repository provider, for its own
1310-
// document or for a nested one: every repository operation under it
1311-
// reaches a clear provider-absence error.
1320+
// The outer `xmd test` command installs no operational repository
1321+
// provider. A test that needs the production behavior exercises an
1322+
// explicit `<Execution host="run">` child, which is an ordinary run and
1323+
// is handed the entrypoint's own installer below.
13121324
unsupportedRepositories,
1325+
installRepositories,
13131326
);
13141327
if (!result.ok) {
13151328
reportFailure(result.error);
@@ -1351,6 +1364,7 @@ function* test(
13511364
{ testing: true },
13521365
installService,
13531366
unsupportedRepositories,
1367+
installRepositories,
13541368
);
13551369
if (!result.ok) {
13561370
reportFailure(result.error, document.relativePath);

‎packages/cli/src/testing-host.ts‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ import type { DeclaredMarkdownComponent } from "@executablemd/core/host";
2626
import { InMemoryStream } from "@executablemd/durable-streams";
2727
import type { DurableEvent } from "@executablemd/durable-streams";
2828
import { forEach } from "@effectionx/stream-helpers";
29-
import { useHostFiles } from "@executablemd/runtime";
29+
import { API, useHostFiles } from "@executablemd/runtime";
3030
import { installWebElicitation } from "@executablemd/web";
3131
import type { Operation, Result } from "effection";
3232
import {
@@ -49,6 +49,7 @@ import type {
4949
} from "@executablemd/testing";
5050
import { installDocumentComponents } from "./cli.ts";
5151
import type { HostServiceInstaller } from "./cli.ts";
52+
import type { RepositoryInstaller } from "./run-repositories.ts";
5253

5354
/** What the entrypoint already decided, and a child must not decide again. */
5455
export interface TestingHostSettings {
@@ -69,6 +70,15 @@ export interface TestingHostSettings {
6970
readonly secretDetection: boolean;
7071
/** The native service adapter this entrypoint supplies. */
7172
readonly installService: HostServiceInstaller;
73+
/**
74+
* How this entrypoint installs repository operations for one execution.
75+
*
76+
* Called again for every child, so an isolated `<Execution host="run">`
77+
* constructs a provider instance of its own: its own invocation identity, its
78+
* own leases and its own Push evidence. Nothing it publishes authorizes its
79+
* parent or a sibling, and nothing they published authorizes it.
80+
*/
81+
readonly installRepositories: RepositoryInstaller;
7282
/**
7383
* How this entrypoint re-invokes itself as the test-agent worker, or why it
7484
* cannot.
@@ -149,6 +159,23 @@ function* runProfileChild(
149159
if (request.host !== "run") {
150160
throw new Error(`the ${request.host} host profile is not available on this entrypoint`);
151161
}
162+
// First, because everything below resolves against it. This scope inherits no
163+
// `API.Env` handler, so without this the child would stand in the *process*
164+
// directory: a `<Dir>` around the `<Execution>` would scope every component
165+
// in it except the child, the root reference would resolve from somewhere the
166+
// document never named, and the repository provider installed below would
167+
// discover its ambient Git from whatever checkout the process was launched
168+
// in. Installed ahead of the root, the provider and the execution, so all
169+
// three agree with the document that asked.
170+
yield* API.Env.around(
171+
{
172+
// deno-lint-ignore require-yield
173+
*cwd(): Operation<string> {
174+
return invocation.cwd;
175+
},
176+
},
177+
{ at: "min" },
178+
);
152179
const root = rootOf(request);
153180
// `--journal` is the only thing that asks `xmd run` for a diagnostic record,
154181
// and a declaration is the only thing that asks a child for one. Neither
@@ -203,6 +230,9 @@ function* runProfileChild(
203230
// Native service authority belongs only to document execution, here as in the
204231
// command that owns it.
205232
yield* settings.installService();
233+
// And repository authority the same way, from the same installer the command
234+
// used — a fresh instance for this child alone.
235+
yield* settings.installRepositories();
206236

207237
const execution = yield* executeInstalled(
208238
{

0 commit comments

Comments
 (0)