Skip to content

Commit 392c006

Browse files
authored
✨ Give an ordinary xmd run the repository vocabulary, and make <Dir> create its target (#643) (#696)
* ✨ Expose the repository vocabulary to an ordinary xmd run (#643) The provider exists; this is what 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 on those runtimes reaches a clear provider-absence error before a lock, a credential, a subprocess or a request exists. That is the whole implementation of the portable half: 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 is on the shared command path; `deno-repositories.ts` assembles the live provider and is imported only by the two Deno entrypoints. The 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 installs no provider here. Giving a child a live one is inseparable from placing it in the document's contextual repository — a child that had authority but discovered the process directory would operate on a checkout nobody named — so both land together, later, as one change. At this level `xmd test`, a nested child and a workflow execution all reach provider absence. The public specifications describe the ordinary profile, the compiled smoke proves the provider and its kernel-released lock survive `deno compile`, and CI carries the smoke as its own step. * ✨ 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. * 📝 Specify persistent Dir creation (#643) * ✨ Make <Dir> create the directory it names (#643) `<Dir path>` installed a working directory and created nothing, so a document that named a directory which was not there ran its content somewhere that did not exist. It now performs one provider-neutral directory act before it installs cwd and before any content expands. `API.Files` gains a mandatory `ensureDirectory`. It recursively creates a missing target, succeeds for an existing directory without replacing it or clearing its contents, and refuses a file or another non-directory at the target or on the way to it. Success carries nothing at all — no path, no handle, and no word on whether this call is what created it — for the same reason `deleteFile` carries nothing: a document that asked for a directory to exist has been answered by its existence, and a caller that could tell the two apart would be branching on a race. The host provider creates directly and persistently. There is no rollback and no teardown removal: a later failure of the content running inside a directory says nothing about whether the directory should exist. It is also the one operation here that accepts an absolute path, which is `<Dir>`'s established exception, so it resolves its own destination rather than inheriting the rule that refuses one. The workflow provider publishes one `workspace_file` effect. The recursive creation runs inside its savepoint, so a refusal after a partial creation leaves neither the parent nor a rolled-back transaction — the effect that follows still commits. An absolute path there is a logical Workspace path used as written, and names nothing on the host. Shared `<Dir>` calls only `API.Files.ensureDirectory`, through core's door that turns an illegal provider throw into a fenced failure. It reaches no `API.Fs`, no `@effectionx/fs`, no runtime API and no Repository composition, and it changes no Repository selection or identity member. `allow={["write"]}` now authorizes persistent recursive creation, so the pinned paired identity is versioned to `@executablemd/workflow/composition/dir-v2#Dir`. A continuation retaining the former identity — which authorized placement that created nothing — refuses before generated execution and before any mutation. The thirteen composition components take their accepted descriptions. Evidence: HF15b, HF24–HF28, FF2, the compiled contract probe, WF23–WF26, WGAC17, ORC6–ORC6i, runtime parity under Deno, Node and Bun, and ORC20. * 🧪 Make the Dir evidence discriminate what it claims (#643) Seven corrections to the previous feedback commit. The production contract, the public `ensureDirectory` export, the versioned `dir-v2#Dir` identity and the thirteen accepted descriptions are unchanged. `Dir.ts` said "It creates nothing", which the change had made false. Its module documentation now describes what it does: ensure or create the target, then expand content there, restore the enclosing directory on the way out, and delete nothing when it does. FF2's shipped-component half searched the escaping error for content markers. That could not tell "the content never expanded" from "the content expanded and its text is not in this message". Sentinel components record whether they ran, so the assertion is about expansion rather than about a string. HF26 and ORC6b covered regular files only. Both now cover the frozen matrix: a regular file and a supported special entry, each at the target and each as an intermediate. The special entry is a symbolic link to a file — a link to a directory is a directory to enter, which is the parity decision both providers make, so using one would have tested the opposite claim. ORC6 inferred ordering from a nested `<File>` landing, which proves nothing because a write creates its own parents. A probe now runs first inside the region and records that the directory already exists and that the contextual working directory is the ensured target. ORC6c inferred cwd restoration after cancellation from where a later run's files landed, but a fresh execution is handed its cwd explicitly. It now reads the contextual directory from inside the region and again from the enclosing scope after the halt. WGAC17 gains the current-admission control as committed evidence: it resumes, completes, and publishes no further effect or root. Root invariance is described as what it is — no published mutation — rather than as a call count, which it is not: an ensure that found the directory already there would publish no root either. The call count is WF26's, which decorates `mkdir` and counts it. Four documentation blocks had been orphaned from their declarations by code inserted between them, WF23's comment still described the ordering proof it no longer used, and `logicalTarget` was a generator that never yielded. * 📝 Prove the generated Dir executed, and say what each observable supports (#643) Comment and evidence corrections. No production behavior changes. WGAC17's shared setup now reads the retained ordered `workspace_file` effects and requires an `ensure-directory` for `/generated` ahead of the nested write to `/generated/inside.md`. That is what says the generated `<Dir>` actually ran under the current admission — the fragment's text says what was asked for, and only the committed order says what happened. Pointing it at a target the run never ensures fails both cases, since the setup guards each. The comments now claim only what their observables support. This test proves the generated Dir effect occurred and that resuming publishes no further effect or root. WF26 proves a completed `<Dir>` replay makes no second low-level `mkdir` call. Root invariance proves neither: an ensure finding the directory already there would publish no root either. The former-identity case no longer claims anything about a second creation — it establishes refusal before generated execution or publication, which is its whole subject. The control's name said "does not create again", which is WF26's claim rather than this one's; it now names what it proves. Two stale comments removed: ORC6's header still said the nested `<File>` landing observes ordering, which the probe beneath it contradicts, and HF26 carried its pre-revision two-case explanation above the corrected four-case one. * 🤖 Regenerate the publish workflow for testing's new runtime dependency (#643) `packages/testing/src/execution-harness.ts` imports `cwd` from `@executablemd/runtime`, so `packages/testing/package.json` gained `@executablemd/runtime` — but the workflow generated from those manifests was not regenerated with it. The generated graph is what orders publication, so the stale copy had `testing` waiting only on `core` and `durable-streams`. It could therefore publish before the `runtime` package it now depends on. CI checks this in every `test-deno` shard by regenerating and diffing, which is why all nine failed together and in under a minute, before any test ran. * 🐛 Write the syntax catalog whole, and state the CLI tier's commit identity (#643) Two failures, both revealed rather than caused by the previous commit: the stale publish workflow had been killing all nine `test-deno` shards before a test ran, so nothing underneath it had been reported yet. ## The catalog was truncated when stdout was a pipe `process.stdout` is synchronous for a file or a terminal and asynchronous for a pipe, and the `syntax` case handed its whole document to `write` without waiting. The run then ended and the process exited with most of the document still in a buffer, so `xmd syntax --json > file` was whole at 89252 bytes while `xmd syntax --json | …` stopped at 65394 — inside a token, which is why the reader saw "Unexpected end of JSON input" rather than a short catalog. This became visible now because this branch registers the repository vocabulary in the catalog, which is what first pushed it past the buffer. The write now waits for the callback, so it finishes before anything can exit. Only that one write is changed. The other large writes in this file stream in chunks rather than handing over a single document, and none of them is near the buffer. ## The CLI tier read the host's Git identity `runOrdinary` installed the provider without saying who a commit is by, so it fell through to the production default — the caller's own `git config`. ORC18 and ORC15 therefore asserted something about who ran them: green on a machine with `user.name` set, `UnresolvedGitIdentityError` on every runner. It now states a fixture identity, the same correction the workflow tier already carries. ORC19 was never affected: it commits inside a subprocess whose environment it builds itself. Verified against a reproduced runner rather than a reading — with `user.useConfigOnly` set and no configuration file, the four CLI suites pass 11/33, and the npm-bin suite passes 1/2 with a rebuilt package. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent fef5de8 commit 392c006

51 files changed

Lines changed: 4206 additions & 347 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,13 @@ jobs:
222222
- name: The <Plan> Component the compiled binary carries
223223
run: deno test --allow-all --frozen scripts/tests/plan-component-compiled.test.ts
224224

225+
# The ordinary repository provider is assembled at a runtime-named
226+
# entrypoint and holds managed checkouts with a kernel-released advisory
227+
# lock, so only the binary shows both surviving `deno compile`. The script
228+
# runs two of them at once against a managed root of its own.
229+
- name: Smoke test repository composition with the compiled binary
230+
run: deno run --allow-all --frozen scripts/smoke-run-composition.ts
231+
225232
# `<Fetch>` resolves from core's registry, requests through the contextual
226233
# Fetch adapter, and detaches the response before binding it. All three
227234
# live in the module graph, so only the binary shows they survived

‎.github/workflows/publish-packages.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ jobs:
9090
version: ${{ needs.version.outputs.value }}
9191

9292
testing:
93-
needs: [version, core, durable-streams]
93+
needs: [version, core, durable-streams, runtime]
9494
uses: ./.github/workflows/publish-one.yml
9595
with:
9696
package: packages/testing

‎architecture.md‎

Lines changed: 103 additions & 58 deletions
Large diffs are not rendered by default.

‎issue-643-implementor-handoff.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Issue #643 — `<Dir>` production-correction handoff
2+
3+
## Continuity
4+
5+
- Stack base commits:
6+
1. `0b02832d136ab9f847cc7a97ef16ba333c013e3a`
7+
2. `7be4b873252e1d4c715e04bdacd03ab5b9ce2916`
8+
3. `e9ff9d60565c9f9986c5371cd3710d4fc122ccaa`
9+
- This correction follows the architecture-artifact commit on top of PR 3.
10+
- Existing PR #689 remains untouched. Pushes and PR editing belong to delivery,
11+
not this feedback step.
12+
- Preserve `scratch/orc19-probe.ts`; do not create, remove, prune or repair a
13+
worktree.
14+
15+
## Settled correction
16+
17+
`<Dir path>` is not placement-only. It performs one provider-neutral semantic
18+
directory operation before it installs cwd or expands content:
19+
20+
- recursively create the specified directory when it is missing;
21+
- use an existing directory without replacing, clearing or otherwise changing
22+
it or its contents;
23+
- refuse a target or intermediate entry that is a file or another
24+
non-directory, before content begins;
25+
- resolve a relative path against the enclosing contextual cwd and preserve the
26+
component's existing absolute-path behavior;
27+
- expand content with the resulting directory as cwd;
28+
- restore the enclosing cwd on success, failure and cancellation;
29+
- leave created directories in place, including after later content failure or
30+
cancellation; and
31+
- change no Repository selection or identity member.
32+
33+
The contract applies to ordinary and workflow runs. Shared `<Dir>` calls only
34+
the mandatory stable `API.Files.ensureDirectory` operation. It does not call
35+
`API.Fs`, `@effectionx/fs`, a runtime API or RepositoryComposition. The absent
36+
Files provider remains fail-closed, and independently loaded package copies
37+
compose through the stable Api name. All four host entrypoints install the host
38+
Files provider, so Node and Bun retain operational `<Dir>` behavior despite
39+
having no ordinary repository provider.
40+
41+
## Provider contracts
42+
43+
The host Files provider resolves the target in the contextual filesystem,
44+
recursively creates it directly, accepts an existing directory and maps every
45+
documented refusal to the shared sanitized vocabulary. It is deliberately
46+
non-transactional: successful creation persists, and neither later content
47+
failure nor cancellation triggers rollback or teardown deletion.
48+
49+
The workflow Files provider publishes exactly one `workspace_file` effect for
50+
the ensure. Recursive mutation runs inside its savepoint. On success, the
51+
mutation, sanitized outcome and resulting Workspace root commit together. A
52+
documented refusal rolls the savepoint back and records the refusal against the
53+
unchanged root. Infrastructure failure or cancellation before commit publishes
54+
neither an outcome nor a root. Completed replay restores the recorded success
55+
and retained root without attempting creation again. No retained field contains
56+
a host path, errno/platform code, raw platform message or cause.
57+
58+
## Generated-XMD authority
59+
60+
The product decision is settled: selecting `allow={["write"]}` intentionally
61+
authorizes `<Dir>`'s persistent recursive directory creation.
62+
63+
Make that authority change visible in retained identity. The paired write-table
64+
entry is `@executablemd/workflow/composition/dir-v2#Dir`. The former
65+
`@executablemd/workflow/composition#Dir` identity authorized placement that
66+
created nothing and must never authorize creation. A continuation retaining the
67+
former identity refuses before generated execution and mutation. Read-only
68+
admissions remain unaffected because they never selected the write table.
69+
70+
## Implementation boundaries
71+
72+
1. Extend the shared `API.Files` contract with mandatory
73+
`ensureDirectory(cwd, path)` returning Effection `Result<Unit>`. Keep the
74+
existing fail-closed terminal and stable namespaced Api.
75+
2. Implement the operation in the host Files provider through asynchronous
76+
Effection filesystem operations. Preserve the host provider's containment
77+
and sanitization rules, including the established absolute-Dir exception.
78+
3. Implement it in the transaction-bound workflow Files provider as one named
79+
`workspace_file` effect and savepoint, using the logical Workspace path and
80+
root-publication protocol already used by file mutations.
81+
4. Change shared `<Dir>` ordering to ensure, then install cwd, then expand
82+
content. Scope teardown restores cwd only.
83+
5. Version the pinned paired Dir origin in the generated write table and cover
84+
continuation refusal from the former identity.
85+
6. Keep Repository composition out of the operation. Do not select, replace or
86+
reconstruct a Repository from a directory path.
87+
7. Update the component description to the already accepted text, without
88+
further product interpretation:
89+
90+
> Create or use a directory. `<Dir path={worktree}>…</Dir>` changes the working directory for its content.
91+
92+
Do not add a second directory API, a test-only provider fallback, host/runtime
93+
detection in shared code, rollback for ordinary host creation or deletion during
94+
Dir teardown.
95+
96+
## Frozen acceptance evidence
97+
98+
Evidence must distinguish every row; one broad happy-path test does not replace
99+
the failure, replay or authority cases.
100+
101+
| ID | Criterion | Discriminating evidence |
102+
| --- | --- | --- |
103+
| ORC6 | Missing directory and ordering | Missing relative parents are created recursively, an absolute target keeps its meaning, and no content begins before the ensure succeeds |
104+
| ORC6a | Existing directory | Existing contents remain byte-identical; the directory is neither replaced nor cleared |
105+
| ORC6b | Non-directory refusal | File and supported special targets, including an intermediate entry, refuse before content with sanitized structural data |
106+
| ORC6c | Cwd restoration | The enclosing cwd is restored after success, printed failure and cancellation |
107+
| ORC6d | Repository invariance | Every Repository identity member and provider selection remains unchanged inside and after Dir |
108+
| ORC6e | Ordinary persistence | Host-created directories remain after success, failed content and cancellation; no teardown delete runs |
109+
| ORC6f | Workflow atomicity | Recursive creation, one `workspace_file` success and its resulting authoritative root commit together before content |
110+
| ORC6g | Workflow refusal rollback | A documented non-directory refusal rolls back its savepoint, creates no partial parent, begins no content and records the unchanged root |
111+
| ORC6h | Workflow replay/cancellation | Completed replay performs no second ensure and restores the retained root; pre-commit cancellation publishes nothing; later content cancellation preserves the committed directory |
112+
| ORC6i | Generated authority | `write` admits only paired `dir-v2#Dir`; the former retained identity refuses before generated execution and creates nothing |
113+
| ORC20 | Retained regression | Repository/Worktree/Git/Issue/PullRequest replay contracts and provider call counts remain unchanged; directory ensure contributes only its own effect/root |
114+
115+
Also extend the shared host Files contract/compiled probe and the absent-provider
116+
suite. Exercise the ordinary component under Deno, Node and Bun because the
117+
host Files provider is their operational boundary. Exercise workflow creation,
118+
existing-directory adoption, refusal rollback, completed replay, current-root
119+
publication and cancellation at the retained provider boundary.
120+
121+
## Feedback handoff
122+
123+
Create one production feedback commit on top of the architecture-artifact
124+
commit after the smallest focused tests that discriminate these rows pass. Hand
125+
back its exact base and SHA, every changed file, every focused command and exact
126+
result, the row-to-test mapping, and any deviation. Do not wait for CI or push
127+
before requesting the architecture verdict.

‎packages/cli/src/bun.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import { runXmd, XMD_VERSION } from "./cli.ts";
1414
import type { UpgradeAssembly } from "./upgrade.ts";
1515
import { unassembledMachineSessions } from "./session-coordinator.ts";
1616
import { unsupportedWorkflowHost } from "./workflow.ts";
17+
import { unsupportedRepositories } from "./run-repositories.ts";
1718
import { useBunService } from "./bun-service.ts";
1819

1920
const ENTRYPOINT = fileURLToPath(import.meta.url);
@@ -59,10 +60,16 @@ await main(function* (args) {
5960
// build either. Advertising the same names is what makes the refusal say so:
6061
// every advertised operation stops before provider work, while ordinary ACP
6162
// work is unaffected.
63+
// The same thirteen repository components, and no provider that operates
64+
// any of them. This runtime has no kernel-released advisory lock to hold a
65+
// managed checkout with, so a Repository, Worktree, Git, Issue or PullRequest
66+
// operation reports an absent provider before a local or remote change could
67+
// happen. `xmd syntax` still describes one language everywhere.
6268
yield* runXmd(
6369
args,
6470
useBunService,
6571
UPGRADE,
72+
unsupportedRepositories,
6673
unsupportedWorkflowHost,
6774
unassembledMachineSessions(),
6875
);

0 commit comments

Comments
 (0)