Skip to content

Commit 4db7b5f

Browse files
committed
πŸ” Read an artifact where nothing may be written beside it
I2 was arranged but not complete. It copied the artifact to a second path and compared the answers, which proves the path is not part of identity β€” and proves nothing at all about the claim underneath it, that inspecting an artifact writes nothing. A directory that merely happened to stay clean is not a directory that could not have been written to. So the copy is inspected while its containing directory refuses new entries. A reader that opened the container for writing, or left a journal, a WAL or a lock next to it, cannot finish there at all. The refusal is proven before the assertions rather than assumed, because a host that quietly ignored the mode change would make every line after it a coincidence. Permissions are restored through this scope's teardown, registered inside the fixture's own removal so it runs first: a failing assertion still leaves the temporary tree removable. Status and history both still answer, the two paths give byte-identical JSON, the human heading names the path each caller supplied, and the file and its directory are unchanged afterwards. The `architecture.md` lifecycle excerpt now says what the surface is. It had drifted before this story β€” no fork lineage on the snapshot and no `export` β€” and it gains the artifact result types and the two sibling operations. The retained pair stays distinct, and the paragraph under it says why: a run ID names live lifecycle authority, a path names evidence somebody is holding, and `WorkflowArtifactSnapshot` extends the retained snapshot rather than restating it. Refs #601
1 parent 3dad621 commit 4db7b5f

2 files changed

Lines changed: 76 additions & 1 deletion

File tree

β€Žarchitecture.mdβ€Ž

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -527,6 +527,12 @@ type ExecutorAcquisition =
527527
| { readonly kind: "acquired"; readonly lock: ExecutorLock }
528528
| { readonly kind: "already-running" };
529529

530+
interface WorkflowForkLineage {
531+
readonly sourceRunId: string;
532+
readonly checkpointEventId: string;
533+
readonly checkpointWorkspaceRootId: string;
534+
}
535+
530536
interface WorkflowLifecycleSnapshot {
531537
readonly record: WorkflowRunRecord;
532538
readonly retrieval?: DefinitionRetrieval;
@@ -536,22 +542,56 @@ interface WorkflowLifecycleSnapshot {
536542
readonly workspaceRootId: string;
537543
};
538544
readonly currentWorkspaceRootId: string;
545+
readonly lineage?: WorkflowForkLineage;
539546
}
540547

541548
interface WorkflowDeletion {
542549
readonly removed: readonly ("run-storage" | "provider-sessions")[];
543550
}
544551

552+
interface XmdArtifactFrontier {
553+
readonly sourceRunId: string;
554+
readonly finalEventId?: string;
555+
readonly currentWorkspaceRootId: string;
556+
}
557+
558+
interface WorkflowArtifactIdentity {
559+
readonly identity: string;
560+
readonly frontier: XmdArtifactFrontier;
561+
}
562+
563+
interface WorkflowArtifactSnapshot extends WorkflowLifecycleSnapshot {
564+
readonly artifact: WorkflowArtifactIdentity;
565+
}
566+
567+
interface WorkflowArtifactHistory {
568+
readonly artifact: WorkflowArtifactIdentity;
569+
readonly entries: readonly WorkflowHistoryEntry[];
570+
}
571+
545572
interface WorkflowLifecycleApi {
546573
acquireExecutor(runId: string): Operation<Result<ExecutorAcquisition>>;
547574
inspect(runId: string): Operation<Result<WorkflowLifecycleSnapshot>>;
548575
list(): Operation<Result<readonly WorkflowLifecycleSnapshot[]>>;
549576
history(runId: string): Operation<Result<readonly WorkflowHistoryEntry[]>>;
577+
inspectArtifact(path: string): Operation<Result<WorkflowArtifactSnapshot>>;
578+
historyArtifact(path: string): Operation<Result<WorkflowArtifactHistory>>;
550579
cancel(runId: string): Operation<Result<WorkflowRunRecord>>;
551580
delete(runId: string): Operation<Result<WorkflowDeletion>>;
581+
export(request: WorkflowExportRequest): Operation<Result<WorkflowExportResult>>;
552582
}
553583
```
554584

585+
The two artifact operations are siblings of the retained-run pair rather than a
586+
widening of it. A run ID names live lifecycle authority in this host's storage;
587+
a path names immutable evidence somebody is holding, and no run has to exist for
588+
it to answer. Their results are the same lifecycle and history values plus which
589+
artifact answered and the boundary it was sealed at, so `WorkflowArtifactSnapshot`
590+
extends the retained snapshot rather than restating it. An artifact carries no
591+
`retrieval`: where a definition could be fetched from now is authority belonging
592+
to the machine that exported. The path is never part of a result, so two copies
593+
of one artifact answer identically.
594+
555595
The executor lock's public fields describe it and never validate it. Lifecycle
556596
transitions accept the exact object separately from their data
557597
through an adapter-private provider operation, just as Workspace transaction

β€Žpackages/cli/tests/workflow-inspection.test.tsβ€Ž

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import { ensure, scoped, spawn, until } from "effection";
1818
import type { Operation } from "effection";
1919
import { ensureDir, exists, readdir, readTextFile, rm, stat, writeTextFile } from "@effectionx/fs";
2020
import { exec } from "@effectionx/process";
21-
import { copyFile, readFile } from "node:fs/promises";
21+
import { chmod, copyFile, readFile } from "node:fs/promises";
2222
import { DatabaseSync } from "node:sqlite";
2323
import { randomUUID } from "node:crypto";
2424
import { fileURLToPath } from "node:url";
@@ -554,6 +554,16 @@ function heading(output: string, label: string): string | undefined {
554554
?.slice(label.length + 2);
555555
}
556556

557+
/** Whether this host really refuses to create that path. */
558+
function* refuses(path: string): Operation<boolean> {
559+
try {
560+
yield* writeTextFile(path, "probe");
561+
return false;
562+
} catch {
563+
return true;
564+
}
565+
}
566+
557567
/** Every name in a directory, so "nothing was written beside it" is checkable. */
558568
function* entries(directory: string): Operation<string[]> {
559569
return (yield* readdir(directory)).sort();
@@ -719,6 +729,25 @@ describe("Tier WFI β€” xmd workflow status and history over a sealed artifact",
719729
const second = join(elsewhere, "same.xmd");
720730
yield* until(copyFile(run.artifact, second));
721731

732+
// The copy is inspected where nothing may be created beside it. That is
733+
// the discriminating arrangement: a reader that opened the container for
734+
// writing, or left a journal, a WAL or a lock next to it, could not
735+
// finish here at all β€” and a directory that merely happened to stay
736+
// clean would not have proved it could not have been written to.
737+
//
738+
// Restored through this scope's teardown rather than at the end of the
739+
// body, so a failing assertion still leaves the fixture removable. It
740+
// runs before `useFixture`'s own removal, which is registered outside it.
741+
yield* until(chmod(elsewhere, 0o555));
742+
yield* ensure(() => until(chmod(elsewhere, 0o755)));
743+
744+
// A directory that still accepted writes would make everything below a
745+
// coincidence, so the refusal is proven rather than assumed.
746+
expect(yield* refuses(join(elsewhere, "probe"))).toBe(true);
747+
748+
const before = yield* fingerprint(second);
749+
const beside = yield* entries(elsewhere);
750+
722751
const answers: string[] = [];
723752
for (const path of [run.artifact, second]) {
724753
for (const action of ["status", "history"]) {
@@ -745,6 +774,12 @@ describe("Tier WFI β€” xmd workflow status and history over a sealed artifact",
745774
expect(heading(here.stdout, "artifact identity")).toBe(
746775
heading(there.stdout, "artifact identity"),
747776
);
777+
778+
// The read-only copy is byte-identical and still the only thing in its
779+
// directory: no sidecar, no journal, no lock.
780+
expect(yield* fingerprint(second)).toBe(before);
781+
expect(yield* entries(elsewhere)).toEqual(beside);
782+
expect(beside).toEqual(["same.xmd"]);
748783
});
749784
});
750785

0 commit comments

Comments
Β (0)