Skip to content

Commit f57bc9a

Browse files
committed
🌳 Name a Git repository and its checkouts inside a workflow run
`<Repository>`, `<Worktree>` and `<Dir>` are the composition a workflow document writes to reach Git. Repository names a locator and gets one primary named-branch checkout; Worktree names a linked checkout inside it; Dir moves the working directory without creating anything. Each of the first two is one durable Workspace effect, so the imported Git bytes, the metadata row, the published Workspace root and the filtered journal result commit together or not at all. Authority is the database. The Deno provider exports a checkout into a disposable host materialization, runs native Git there and imports the result back inside the same transaction, reducing the absolute paths Git writes into a linked worktree's administration to Workspace paths first. A partial replay therefore reattaches and verifies after the remote and every materialization are gone, without cloning anything; a completed replay installs no provider at all. Retained state that disagrees with the record is a fatal stale-input condition that `<PrintErrors>` cannot downgrade. Schema version 1 is amended in place, per the maintainer decision on #293: Repository and Worktree creation records join it, and a database an earlier development build produced is refused as an incomplete pre-release. There is no version 2, no migration and no legacy reader. Records are creation identity only — HEAD, refs, index and linked-worktree administration live in the versioned Workspace filesystem, so one selected root recovers the Git state of that frontier. The Git operations of §7 remain unbuilt and belong to #294. Refs #293
1 parent 20bd894 commit f57bc9a

29 files changed

Lines changed: 3500 additions & 311 deletions

‎architecture.md‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -229,8 +229,9 @@ that filtered it.
229229

230230
WorkflowRun schema version 1 is complete in place. It contains the run records,
231231
filtered journal, pinned Cloudflare DOFS version-5 structure, immutable
232-
Workspace-root tables, current-root state, and a non-null Workspace-root
233-
association on every journal event. A fresh run starts with one
232+
Workspace-root tables, current-root state, a non-null Workspace-root
233+
association on every journal event, and the Repository and Worktree creation
234+
records #293 added to it. A fresh run starts with one
234235
content-addressed root manifest describing only the root directory, empty
235236
retained manifest and blob reference sets, and the corresponding root-only DOFS
236237
frontier.
@@ -736,6 +737,26 @@ Complete schema version 1 therefore remains one exact shape. Any later durable
736737
input-delivery record for #300 requires its own schema-version decision and
737738
strict recognition amendment.
738739

740+
Issue #293 amended that exact shape in place rather than introducing a second
741+
version. This pre-release carries no persistence compatibility obligation, so
742+
Repository and Worktree creation records joined version 1 and every database an
743+
earlier development build produced is refused as an incomplete pre-release.
744+
There is no version 2, no migration, no legacy reader and no upgrade path, and
745+
strict recognition compares the amended declaration exactly.
746+
747+
A Repository record holds a Workspace-local name, the admitted credential-free
748+
locator and its fingerprint, the requested base or its absence, the commit
749+
pinned once at creation, the initial primary branch, the object format and a
750+
stable Workspace-relative checkout path. A Worktree record holds its
751+
Repository's name, its own name, the requested branch, the requested base or
752+
its absence, the creation commit and its checkout path. Both are immutable
753+
creation identity. Current HEAD, refs, index, checkout and linked-worktree
754+
administration live in the versioned Workspace filesystem, so one selected
755+
Workspace root recovers the Git state belonging to that frontier without any
756+
unversioned "current commit" column to disagree with it. The locator is stored
757+
beside the record rather than inside it: compatibility needs the bytes, while
758+
the journal and the document receive only the fingerprint.
759+
739760
## Workflow Workspace
740761

741762
The command selects the environment; the document describes the procedure.
@@ -2060,8 +2081,9 @@ Status is measured against main.
20602081
| `ephemeral eval` | reconstructs live middleware and bindings without a journal entry | built on main |
20612082
| `useWorkflowServiceDenial()` | provides a non-delegating workflow service denial provider, installed inside every start and resume execution scope | built on the #366 stack |
20622083
| `xmd workflow start` / `xmd workflow resume` | starts or resumes a workflow run from the CLI, under the Deno entrypoints only | built on the #366 stack; both acquire #367's executor lock before any lifecycle transition |
2063-
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack; repository, process and attachment capabilities unbuilt (#218) |
2064-
| Repository / Worktree / transactional Git effects | compose named checkouts and publish local mutations with their journal result | defined in `specs/workflow-workspace-spec.md`, unbuilt |
2084+
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack and Repository/Worktree composition on the #293 stack; process capabilities unbuilt (#218) |
2085+
| `<Repository>` / `<Worktree>` / `<Dir>` composition | names a Git repository and its linked checkouts inside the run-owned Workspace, installs each as contextual working directory, and retains creation identity beside the retained Git bytes | built on the #293 stack, Deno provider only |
2086+
| transactional Git effects (`Git.Switch` / `Git.Add` / `Git.Commit`) | publish local Git mutations with their journal result | defined in `specs/workflow-workspace-spec.md`, unbuilt (#294) |
20652087
| 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 |
20662088
| 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 |
20672089
| history fork | creates a new run from one compatible checkpoint and retained Workspace root | defined in `specs/workflow-workspace-spec.md`, unbuilt (#368) |

‎packages/workflow/deno.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,13 @@ export type { WorkflowLifecycleOptions } from "./src/deno/lifecycle.ts";
3838
export { hashRunId, workflowRunLock, workflowRunPath } from "./src/deno/path.ts";
3939
export { APPLICATION_ID, SCHEMA_VERSION } from "./src/deno/schema.ts";
4040
export { withWorkflowWorkspace } from "./src/deno/workspace/host.ts";
41+
export type { WorkflowWorkspaceOptions } from "./src/deno/workspace/host.ts";
42+
export { WORKSPACE_REPOSITORY, WORKSPACE_WORKTREE } from "./src/deno/composition/provider.ts";
43+
export type {
44+
CompositionObserver,
45+
CompositionProviderOptions,
46+
} from "./src/deno/composition/provider.ts";
47+
export { denoRepositoryHost } from "./src/deno/composition/host.ts";
48+
export type { GitInvocation, GitOutcome, RepositoryHost } from "./src/deno/composition/host.ts";
4149
export { WORKSPACE_FILE } from "./src/deno/workspace/files.ts";
4250
export { WORKSPACE_ROOT } from "./src/deno/workspace/logical-path.ts";

‎packages/workflow/mod.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,34 @@ export { getWorkflowRun, retainedWorkflowInstallation, workflowInstallation } fr
4141
export type { WorkflowRun } from "./src/run.ts";
4242
export { useWorkflowServiceDenial, WorkflowServiceDeniedError } from "./src/service-denial.ts";
4343

44+
export { RepositoryComposition } from "./src/composition/api.ts";
45+
export type { RepositoryCompositionApi } from "./src/composition/api.ts";
46+
export { currentRepository, RepositoryContext } from "./src/composition/context.ts";
47+
export type { RepositoryContextApi } from "./src/composition/context.ts";
48+
export {
49+
RepositoryCompositionError,
50+
RepositoryCompositionProtocolError,
51+
RepositoryCompositionProviderError,
52+
RepositoryStaleStateError,
53+
WorktreeCompositionError,
54+
} from "./src/composition/errors.ts";
55+
export type { RepositoryFailureReason, WorktreeFailureReason } from "./src/composition/errors.ts";
56+
export {
57+
parseRepositoryRecord,
58+
parseWorktreeRecord,
59+
repositoryRecordJson,
60+
sameRepositoryRecord,
61+
sameWorktreeRecord,
62+
worktreeRecordJson,
63+
} from "./src/composition/records.ts";
64+
export type {
65+
RepositoryCreationRequest,
66+
RepositoryRecord,
67+
WorktreeCreationRequest,
68+
WorktreeRecord,
69+
} from "./src/composition/records.ts";
70+
export { useCompositionComponents } from "./src/composition/installation.ts";
71+
4472
export { WorkspaceCoordination, WorkspaceCoordinationProviderError } from "./src/workspace/api.ts";
4573
export type { WorkspaceCoordinationApi } from "./src/workspace/api.ts";
4674
export { createDurableWorkspaceOperation } from "./src/workspace/effect.ts";
Lines changed: 47 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,23 @@
11
/**
2-
* The provider-neutral Repository/Worktree composition API.
2+
* The provider-neutral Repository/Worktree composition Api.
33
*
4-
* Repository and Worktree components ask this Api for durable work; the
5-
* installed provider decides how to do it. The shared package names no
6-
* subprocess, no filesystem and no runtime detection. A workflow host that
7-
* has authority to touch a Git checkout — the Deno host, for now — installs a
8-
* concrete provider inside its `withWorkflowWorkspace()` attachment.
4+
* Repository and Worktree components ask this Api for work; the installed
5+
* provider decides how to do it. This package names no subprocess, no host
6+
* filesystem and no runtime: a workflow host with the authority to touch a Git
7+
* checkout — the Deno host, for now — installs a concrete provider inside its
8+
* `withWorkflowWorkspace()` attachment.
99
*
10-
* The default handler throws. There is no in-memory fallback: a Repository
11-
* that "starts" without an installed provider would silently retain nothing.
10+
* Each component performs two steps against it, and the split is what makes
11+
* replay work. **Creation** is the durable half: it clones, resolves, pins and
12+
* retains, and a completed one restores from the journal without contacting
13+
* anything. **Attachment** is the ephemeral half: it runs every time, live or
14+
* replayed, and its job is to rebuild the live facade and check that the
15+
* retained state the journal selected is still the state that is there. Partial
16+
* replay therefore reattaches without recreating, and a retained checkout that
17+
* has gone missing is discovered where it can still stop the run.
18+
*
19+
* The default handler throws. There is no in-memory fallback: a Repository that
20+
* "starts" without a provider would retain nothing while claiming it had.
1221
*/
1322

1423
import { type Api, createApi } from "@effectionx/context-api";
@@ -21,42 +30,47 @@ import type {
2130
WorktreeRecord,
2231
} from "./records.ts";
2332

24-
/** What a component sends back after the provider settled a request. */
25-
export interface RepositoryCompositionResult {
26-
readonly record: RepositoryRecord;
27-
}
28-
29-
export interface WorktreeCompositionResult {
30-
readonly record: WorktreeRecord;
31-
}
32-
3333
export interface RepositoryCompositionApi {
3434
/**
35-
* Install or attach the named Repository under the current workflow run,
36-
* returning the frozen record. Called by the Repository component under a
37-
* live or partial attachment; a completed replay never reaches here.
35+
* Create or restore the named Repository's creation identity.
36+
*
37+
* One durable effect. A live first reach authorizes the locator, resolves the
38+
* base once, pins the commit and retains the checkout; a replayed one returns
39+
* what was retained without reaching a remote.
3840
*/
39-
createRepository(
40-
request: RepositoryCreationRequest,
41-
): Operation<RepositoryCompositionResult>;
41+
createRepository(request: RepositoryCreationRequest): Operation<RepositoryRecord>;
42+
4243
/**
43-
* Install or attach the named Worktree inside the given Repository. Called
44-
* by the Worktree component; the enclosing lexical Repository provides the
45-
* Repository name.
44+
* Rebuild the live facade for a Repository whose creation identity is settled,
45+
* and verify that the Workspace still holds the state that identity names.
46+
*
47+
* Ephemeral: it appends nothing and is performed on every execution.
4648
*/
47-
createWorktree(request: WorktreeCreationRequest): Operation<WorktreeCompositionResult>;
49+
attachRepository(record: RepositoryRecord): Operation<void>;
50+
51+
/** Create or restore the named Worktree's creation identity, as one durable effect. */
52+
createWorktree(request: WorktreeCreationRequest): Operation<WorktreeRecord>;
53+
54+
/** Rebuild and verify a settled Worktree's live facade. */
55+
attachWorktree(record: WorktreeRecord): Operation<void>;
4856
}
4957

5058
export const RepositoryComposition: Api<RepositoryCompositionApi> =
5159
createApi<RepositoryCompositionApi>("executablemd.workflow.composition.repository", {
5260
// deno-lint-ignore require-yield
53-
*createRepository(
54-
_request: RepositoryCreationRequest,
55-
): Operation<RepositoryCompositionResult> {
56-
throw new RepositoryCompositionProviderError("createRepository()");
61+
*createRepository(_request: RepositoryCreationRequest): Operation<RepositoryRecord> {
62+
throw new RepositoryCompositionProviderError("<Repository>");
63+
},
64+
// deno-lint-ignore require-yield
65+
*attachRepository(_record: RepositoryRecord): Operation<void> {
66+
throw new RepositoryCompositionProviderError("<Repository>");
67+
},
68+
// deno-lint-ignore require-yield
69+
*createWorktree(_request: WorktreeCreationRequest): Operation<WorktreeRecord> {
70+
throw new RepositoryCompositionProviderError("<Worktree>");
5771
},
5872
// deno-lint-ignore require-yield
59-
*createWorktree(_request: WorktreeCreationRequest): Operation<WorktreeCompositionResult> {
60-
throw new RepositoryCompositionProviderError("createWorktree()");
73+
*attachWorktree(_record: WorktreeRecord): Operation<void> {
74+
throw new RepositoryCompositionProviderError("<Worktree>");
6175
},
6276
});
Lines changed: 46 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,26 @@
11
/**
2-
* `<Dir path=".." >` — lexical working-directory scope
2+
* `<Dir path="..">` — lexical working directory
33
* (specs/workflow-workspace-spec.md §6.3).
44
*
5-
* One meaning: install `path` as contextual `Env.cwd` for the content, and
6-
* restore the enclosing cwd on success, failure or cancellation. Performs no
7-
* durable effect and creates nothing. Self-closing `<Dir />` is invalid;
8-
* there is nothing to render and no cwd to inherit.
5+
* One meaning and one effect on the world: the content expands with `path` as
6+
* the contextual working directory, and the enclosing one is restored when the
7+
* invocation ends — on success, failure and cancellation alike, because the
8+
* installation lives on the invocation's own scope.
9+
*
10+
* It creates nothing and retains nothing. A `<Dir>` inside a `<Repository>`
11+
* leaves that Repository contextual, which is what lets the self-closing
12+
* Worktree spelling work: the path is bound by `as`, `<Dir>` moves the working
13+
* directory to it, and the Repository a later Git component would act on is
14+
* still the enclosing one.
15+
*
16+
* Self-closing `<Dir />` is invalid. A working directory installed for no
17+
* content is a directory nothing runs in, and silently rendering nothing would
18+
* hide a document that meant to write children.
919
*/
1020

11-
import { API } from "@executablemd/runtime";
12-
import { content, hasContent } from "@executablemd/core";
13-
import { type Operation, scoped } from "effection";
21+
import { API, cwd } from "@executablemd/runtime";
22+
import { content, hasContent, printErrors } from "@executablemd/core";
23+
import type { Operation } from "effection";
1424
import type { Json } from "@executablemd/durable-streams";
1525

1626
export const props = {
@@ -26,27 +36,38 @@ export class DirInvocationError extends Error {
2636
override name = "DirInvocationError";
2737
}
2838

29-
export default function* Dir(props: Record<string, Json>): Operation<string> {
30-
const path = String(props.path);
39+
export default printErrors(function* Dir(props: Record<string, Json>): Operation<string> {
40+
const path = props.path;
41+
if (typeof path !== "string" || path === "") {
42+
throw new DirInvocationError("<Dir> needs a non-empty path.");
43+
}
44+
3145
if (!(yield* hasContent())) {
3246
throw new DirInvocationError(
3347
`<Dir path=${JSON.stringify(path)} /> is invalid: Dir installs a working directory for ` +
34-
"its content, and a self-closing invocation has none. Write it as <Dir path=" +
35-
JSON.stringify(path) +
36-
">…</Dir>.",
48+
`its content, and a self-closing invocation has none. Write it as <Dir path=` +
49+
`${JSON.stringify(path)}>…</Dir>.`,
3750
);
3851
}
3952

40-
return yield* scoped(function* () {
41-
yield* API.Env.around(
42-
{
43-
// deno-lint-ignore require-yield
44-
*cwd(): Operation<string> {
45-
return path;
46-
},
53+
// A bound Workspace path is absolute and is used as written; anything else is
54+
// read the way every other authored path is read — against the directory the
55+
// document is already working in. `<Dir path="nested">` inside a Repository
56+
// therefore means that Repository's `nested`, and a `<Dir>` that meant the
57+
// Workspace root would be the surprising one.
58+
const enclosing = yield* cwd();
59+
const target = path.startsWith("/")
60+
? path
61+
: `${enclosing.endsWith("/") ? enclosing.slice(0, -1) : enclosing}/${path}`;
62+
63+
yield* API.Env.around(
64+
{
65+
// deno-lint-ignore require-yield
66+
*cwd(): Operation<string> {
67+
return target;
4768
},
48-
{ at: "min" },
49-
);
50-
return yield* content();
51-
});
52-
}
69+
},
70+
{ at: "min" },
71+
);
72+
return yield* content();
73+
});

0 commit comments

Comments
 (0)