@yaag/runtime 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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";
@@ -29,7 +30,8 @@ export interface RunCheckpointOptions {
  * What one publication attempt did. `published` covers both a written artifact
  * and a Run that keeps none. `displaced` carries the error that must become the
  * Run's outcome. `lost` reports a Checkpoint the Run asked for and did not get,
- * while a primary program error keeps the outcome.
+ * while the Run keeps its own outcome — a completed result, or a primary
+ * program error (ADR-0021 amendment).
  */
 export type RunCheckpointResult =
   | { readonly kind: "published" }
@@ -65,15 +67,24 @@ export async function publishRunCheckpoint(
       writeRecordingDiagnostic(error);
       return { kind: "lost", message: String(error) };
     }
-    if (options.outcome === "stopped") {
-      return {
-        kind: "displaced",
-        error: new Error(`run stopped but is not restorable: ${String(error)}`, { cause: error }),
-      };
+    // A completed Run keeps its outcome and its result: the work is done, and
+    // no restorability promise is broken. The lost Cassette rides
+    // run_end.checkpointLost and the stderr diagnostic instead of displacing
+    // the outcome (ADR-0021 amendment).
+    if (options.outcome === "completed") {
+      const message = `run completed but its Cassette could not be written: ${String(error)}`;
+      writeRecordingDiagnostic(message);
+      return { kind: "lost", message };
     }
-    // A requested checkpoint silently going missing is worse than rejecting an
-    // otherwise successful Run (ADR-0021).
-    return { kind: "displaced", error };
+    // A pausing or stopped Run promises restorability, and a Checkpoint that
+    // did not land makes that acknowledgement a lie, so the failure takes the
+    // outcome (ADR-0021: a flush failure is a hard failure there).
+    return {
+      kind: "displaced",
+      error: new Error(`run ${options.outcome} but is not restorable: ${String(error)}`, {
+        cause: error,
+      }),
+    };
   }
 }
 
@@ -82,15 +93,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 ?? (() => {});