@yaag/runtime 0.2.0 → 0.3.0

package/package.json

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

package/src/cassette-schema.ts

@@ -139,6 +139,7 @@ const CassetteRunSchema = Type.Object({
     ),
   ),
   programFile: Type.Optional(Type.String()),
+  programSource: Type.Optional(Type.String()),
   args: Type.Optional(Type.Unknown()),
   programHash: Type.Optional(Type.String()),
 });

package/src/cassette.ts

@@ -22,8 +22,10 @@ export interface CassetteRun {
   readonly outcome: RunOutcome;
   /** Invocation identity: what a resume is about to re-execute. */
   readonly programFile?: string;
+  /** Inline Program source text; identity for a Run with no program file (ADR-0033). */
+  readonly programSource?: string;
   readonly args?: unknown;
-  /** Advisory content hash of the program file; SHA-256 hex. */
+  /** Advisory content hash of the program file, or of the inline source; SHA-256 hex. */
   readonly programHash?: string;
 }
 

package/src/program-hash.ts

@@ -0,0 +1,9 @@
+/**
+ * One advisory content hash, shared by the modules that record a program's
+ * identity and the modules that compare it (ADR-0033).
+ */
+
+/** Advisory content hash of a program's bytes or inline source; SHA-256 hex. */
+export function sha256Hex(input: string | ArrayBuffer): string {
+  return new Bun.CryptoHasher("sha256").update(input).digest("hex");
+}

package/src/resume-identity.ts

@@ -0,0 +1,47 @@
+/**
+ * The advisory comparison between a loaded Cassette's recorded program identity
+ * and the program this Run executes (ADR-0033).
+ */
+import type { Cassette } from "./cassette.ts";
+import { sha256Hex } from "./program-hash.ts";
+import type { ProgramIdentity } from "./run-checkpoint.ts";
+
+/**
+ * Warns when a Cassette's recorded program identity does not match the program
+ * this Run executes. Advisory only: the caller always supplies the program and
+ * the Cassette supplies the history, so a mismatch never stops the Run
+ * (ADR-0033). Returns null when nothing inline is involved, so file-to-file
+ * resume behaviour is unchanged.
+ */
+export function programIdentityWarning(
+  cassette: Cassette,
+  path: string,
+  program: ProgramIdentity,
+): string | null {
+  const recorded = cassette.run.programSource;
+  const given = program.programSource;
+  if (recorded === undefined && given === undefined) return null;
+  if (recorded !== undefined && given !== undefined) {
+    if (recorded === given) return null;
+    const recordedHash = cassette.run.programHash ?? sha256Hex(recorded);
+    return (
+      `cassette "${path}" recorded a different inline program: ` +
+      `recorded hash ${recordedHash}, given hash ${sha256Hex(given)}; ` +
+      "the Cassette gives history only, and this Run continues with the source you gave (ADR-0033)"
+    );
+  }
+  if (recorded !== undefined) {
+    const file = program.programFile;
+    if (file === undefined) return null;
+    return (
+      `cassette "${path}" recorded an inline program, and this Run runs the program file "${file}"; ` +
+      "the Cassette gives history only, and this Run continues with the program you gave"
+    );
+  }
+  const recordedFile = cassette.run.programFile;
+  if (recordedFile === undefined) return null;
+  return (
+    `cassette "${path}" recorded the program file "${recordedFile}", and this Run runs an inline program; ` +
+    "the Cassette gives history only, and this Run continues with the program you gave"
+  );
+}

package/src/run-checkpoint.ts

@@ -3,6 +3,7 @@ import { dirname } from "node:path";
 import type { CassetteCollector, CassetteRun } from "./cassette.ts";
 import { publishCassette } from "./cassette-publish.ts";
 import type { RunOutcome } from "./events.ts";
+import { sha256Hex } from "./program-hash.ts";
 
 /** What a resume is about to re-execute; resolved once, at Run start. */
 export type RunIdentity = Omit<CassetteRun, "outcome">;
@@ -92,11 +93,25 @@ export async function ensureCheckpointDirectory(
   await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
 }
 
+/** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
+export interface ProgramIdentity {
+  readonly programFile?: string;
+  /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
+  readonly programSource?: string;
+}
+
 /** Resolves what a resume re-executes. The program hash is advisory only. */
 export async function resolveRunIdentity(
-  programFile: string | undefined,
+  program: ProgramIdentity,
   args: unknown,
 ): Promise<RunIdentity> {
+  // An Inline Program's file is a temporary path, and no artifact may name it,
+  // so the inline arm drops `programFile` even when the caller supplies one.
+  if (program.programSource !== undefined) {
+    const programSource = program.programSource;
+    return { programSource, args, programHash: sha256Hex(programSource) };
+  }
+  const programFile = program.programFile;
   if (programFile === undefined) return {};
   const programHash = await hashProgram(programFile);
   return { programFile, args, ...(programHash === null ? {} : { programHash }) };
@@ -128,8 +143,7 @@ function isMissingFile(error: unknown): boolean {
 /** Advisory only: an unreadable program file omits the hash and never fails the Run. */
 async function hashProgram(programFile: string): Promise<string | null> {
   try {
-    const bytes = await Bun.file(programFile).arrayBuffer();
-    return new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+    return sha256Hex(await Bun.file(programFile).arrayBuffer());
   } catch {
     return null;
   }

package/src/run.ts

@@ -16,8 +16,10 @@ import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "./
 import { liveTransport } from "./live-transport.ts";
 import { recordingTransport } from "./recording-transport.ts";
 import { replayTransport } from "./replay-transport.ts";
+import { programIdentityWarning } from "./resume-identity.ts";
 import { resumeTransport } from "./resume-transport.ts";
 import {
+  type ProgramIdentity,
   publishRunCheckpoint,
   type RunCheckpointResult,
   resolveRunIdentity,
@@ -44,6 +46,11 @@ export interface RunOptions {
    * extension declarations. This is Run context, never an Agent working directory.
    */
   readonly programFile?: string;
+  /**
+   * Inline Program source text, recorded as the Run's identity when there is no
+   * program file (ADR-0033). It never resolves extension paths.
+   */
+  readonly programSource?: string;
   /** Resolves pi's enabled skills for live restriction requests. */
   readonly skillProbe?: SkillProbeFactory;
   /** Write every public transport-seam frame once the Run settles. */
@@ -83,8 +90,14 @@ export async function executeRun<Args, Result>(
   } catch (error) {
     writeRecordingDiagnostic(error);
   }
-  const replay = await loadReplay(options.replay);
-  const resume = await loadResume(options.resume);
+  // Built once, so the identity a resume compares and the identity an artifact
+  // records cannot drift apart.
+  const programIdentity: ProgramIdentity = {
+    ...(options.programFile === undefined ? {} : { programFile: options.programFile }),
+    ...(options.programSource === undefined ? {} : { programSource: options.programSource }),
+  };
+  const replay = await loadReplay(options.replay, programIdentity);
+  const resume = await loadResume(options.resume, programIdentity);
   const definition = programDefinition(program);
   // Collection is universal so every Run can checkpoint, and every Run flushes
   // that collection at each Ask boundary (ADR-0031). Only a stopped Run and a
@@ -96,7 +109,7 @@ export async function executeRun<Args, Result>(
   // Fixed here, so every Ask-boundary flush and the settlement write one file,
   // and so run_start can name it (ADR-0031).
   const destination = options.record ?? join(checkpointDir, checkpointFileName());
-  const identity = await resolveRunIdentity(options.programFile, args);
+  const identity = await resolveRunIdentity(programIdentity, args);
   const checkpoint = { collector, record: options.record, destination, identity };
   try {
     assertArgs<Args>(definition.args, args);
@@ -169,23 +182,45 @@ export async function executeRun<Args, Result>(
   return settled.value;
 }
 
-/** Loads a strict-replay source, which must be a settled Cassette (ADR-0031). */
-async function loadReplay(path: string | undefined): Promise<Cassette | null> {
+/**
+ * Loads a strict-replay source, which must be a settled Cassette (ADR-0031). A
+ * replay of an Inline Program follows the same rule as a resume: a recorded
+ * identity that differs from the given program warns once, and the Run goes on.
+ */
+async function loadReplay(
+  path: string | undefined,
+  program: ProgramIdentity,
+): Promise<Cassette | null> {
   if (path === undefined) return null;
   const cassette = await loadCassette(path);
   assertReplayable(cassette, path);
+  warnOnIdentity(cassette, path, program);
   return cassette;
 }
 
-/** Loads a resume source, warning once when it came from a hard death (ADR-0031). */
-async function loadResume(path: string | undefined): Promise<Cassette | null> {
+/**
+ * Loads a resume source, warning once when it came from a hard death (ADR-0031),
+ * and once more when its recorded program identity differs from this Run's
+ * program (ADR-0033).
+ */
+async function loadResume(
+  path: string | undefined,
+  program: ProgramIdentity,
+): Promise<Cassette | null> {
   if (path === undefined) return null;
   const cassette = await loadCassette(path);
   const warning = interruptedResumeWarning(cassette, path);
   if (warning !== null) writeRecordingDiagnostic(warning);
+  warnOnIdentity(cassette, path, program);
   return cassette;
 }
 
+/** Advisory only: a Cassette gives history, and never the program to run (ADR-0033). */
+function warnOnIdentity(cassette: Cassette, path: string, program: ProgramIdentity): void {
+  const warning = programIdentityWarning(cassette, path, program);
+  if (warning !== null) writeRecordingDiagnostic(warning);
+}
+
 /** What the Orchestration Program body produced, before the Run acknowledges it. */
 type Settlement<Result> =
   | { readonly ok: true; readonly value: Result }