@yaag/runtime 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "publishConfig": {
     "access": "public"
   },

package/src/cassette/index.ts

@@ -30,6 +30,7 @@ export { programIdentityWarning } from "./resume-identity.ts";
 export { resumeTransport } from "./resume-transport.ts";
 export {
   type ProgramIdentity,
+  prepareRecordDestination,
   publishRunCheckpoint,
   type RunCheckpointResult,
   resolveRunIdentity,

package/src/cassette/run-checkpoint.ts

@@ -1,5 +1,6 @@
 import { mkdir, unlink } from "node:fs/promises";
 import { dirname } from "node:path";
+import { YaagError } from "../errors.ts";
 import type { RunOutcome } from "../events.ts";
 import type { CassetteCollector, CassetteRun } from "./cassette.ts";
 import { publishCassette } from "./cassette-publish.ts";
@@ -72,8 +73,14 @@ export async function publishRunCheckpoint(
       };
     }
     // A requested checkpoint silently going missing is worse than rejecting an
-    // otherwise successful Run (ADR-0021).
-    return { kind: "displaced", error };
+    // otherwise successful Run (ADR-0021). The two facts stay readable: the
+    // program completed, and the Cassette did not land.
+    return {
+      kind: "displaced",
+      error: new Error(`run completed but its Cassette could not be written: ${String(error)}`, {
+        cause: error,
+      }),
+    };
   }
 }
 
@@ -82,15 +89,40 @@ function keepsArtifact(options: RunCheckpointOptions): boolean {
 }
 
 /**
- * Creates the checkpoint directory a Run owns. An explicit `--record` path keeps
- * today's rule that its directory must already exist.
+ * Creates the directory the Run's artifact goes into. A `--record` path names
+ * where the artifact goes, so yaag creates the chain that path implies rather
+ * than refusing. ADR-0021 makes `--record` fix the destination path only, and a
+ * path yaag can make is a destination yaag makes. The checkpoint directory yaag owns stays
+ * private; a user-named `--record` directory takes the process umask, because it
+ * lives in the user's own tree.
  */
 export async function ensureCheckpointDirectory(
   record: string | undefined,
   destination: string,
 ): Promise<void> {
-  if (record !== undefined) return;
-  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+  const directory = dirname(destination);
+  if (record === undefined) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    return;
+  }
+  await mkdir(directory, { recursive: true });
+}
+
+/**
+ * Makes the directory chain of the `--record` path at Run start, and rejects the
+ * Run before the first spawn when that chain cannot exist. It does not prove the
+ * destination writable: an existing directory that refuses a write, or a name
+ * already taken, still fails later, at publication.
+ */
+export async function prepareRecordDestination(record: string): Promise<void> {
+  try {
+    await ensureCheckpointDirectory(record, record);
+  } catch (error) {
+    throw new YaagError(
+      "RECORD_PATH_UNUSABLE",
+      `cannot create the Cassette directory ${dirname(record)}: ${String(error)}`,
+    );
+  }
 }
 
 /** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */

package/src/errors.ts

@@ -48,6 +48,7 @@ export type YaagErrorCode =
   | "ARGS_INVALID" // arguments failed schema validation before the Run started
   | "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema
   | "OPTIONS_CONFLICT" // incompatible Run options were supplied
+  | "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
   | "REPLAY_DIVERGED" // replayed program differed from its Cassette
   | "RESUME_REFUSED" // resume metadata is absent or the recorded tree moved
   | "RUN_CLOSED" // spawn was requested after the Run began settling

package/src/run/run.ts

@@ -14,6 +14,7 @@ import {
   interruptedResumeWarning,
   loadCassette,
   type ProgramIdentity,
+  prepareRecordDestination,
   programIdentityWarning,
   publishRunCheckpoint,
   type RunCheckpointResult,
@@ -133,6 +134,9 @@ export async function executeRun<Args, Result>(
     await publishRunCheckpoint({ outcome: "failed", ...checkpoint });
     throw error;
   }
+  // The directory of the --record path is made before any Agent starts, so a Run
+  // whose Cassette can never land does not do its work first and fail last.
+  if (options.record !== undefined) await prepareRecordDestination(options.record);
 
   let summary: RunSummary = initialSummary();
   const sink: StampedEventSink = options.events ?? (() => {});