@michaelrwalker/stagehand 0.2.0 → 0.4.0

package/dist/cache.js

@@ -0,0 +1,120 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+/* -------------------------------------------------------------------------- */
+/* Stores                                                                      */
+/* -------------------------------------------------------------------------- */
+/** Lives for the lifetime of the process. Useful in tests, and for re-runs. */
+export function memoryStore() {
+    const slots = new Map();
+    return {
+        read: (slot) => slots.get(slot),
+        write: (slot, entry) => {
+            slots.set(slot, entry);
+        },
+        clear: (slot) => {
+            slots.delete(slot);
+        },
+    };
+}
+/**
+ * One JSON file, holding every slot that points at it. Several phases may
+ * share a path safely.
+ *
+ * A missing, unreadable or malformed file all mean the same thing — no cache
+ * yet — so deleting the file is always a valid way to start over. Values must
+ * survive `JSON.stringify`; anything that does not (a `Date`, a class
+ * instance) comes back as its JSON shape, which is what `schema` is for.
+ */
+export function fileStore(filePath) {
+    const target = resolve(filePath);
+    const readAll = async () => {
+        try {
+            const parsed = JSON.parse(await readFile(target, "utf8"));
+            if (parsed === null || typeof parsed !== "object")
+                return {};
+            return parsed;
+        }
+        catch {
+            return {};
+        }
+    };
+    // Written through a temp file so an interrupted run cannot leave a
+    // half-serialised cache behind for the next one to choke on.
+    const writeAll = async (data) => {
+        await mkdir(dirname(target), { recursive: true });
+        const temp = `${target}.${process.pid}.tmp`;
+        await writeFile(temp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+        await rename(temp, target);
+    };
+    return {
+        async read(slot) {
+            const entry = (await readAll())[slot];
+            return isEntry(entry) ? entry : undefined;
+        },
+        async write(slot, entry) {
+            const data = await readAll();
+            data[slot] = entry;
+            await writeAll(data);
+        },
+        async clear(slot) {
+            const data = await readAll();
+            if (!Object.hasOwn(data, slot))
+                return;
+            delete data[slot];
+            await writeAll(data);
+        },
+    };
+}
+/** A hand-edited or older-format file should read as a miss, not as a crash. */
+function isEntry(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "value" in value &&
+        typeof value.savedAt === "number");
+}
+/* -------------------------------------------------------------------------- */
+/* Runtime                                                                     */
+/* -------------------------------------------------------------------------- */
+/** `cache: someStore` is shorthand for `cache: { store: someStore }`. */
+export function normalizeCache(source) {
+    if (!source)
+        return undefined;
+    if (typeof source.read === "function") {
+        return { store: source };
+    }
+    return source;
+}
+const MISS = { hit: false };
+/**
+ * Read an entry and put it through every gate. A failure at any gate is a
+ * miss — the work runs and the entry is replaced — never an error.
+ */
+export async function readCache(cache, slot, input, ctx, mode) {
+    if (mode === "off" || mode === "refresh")
+        return MISS;
+    const entry = await cache.store.read(slot);
+    if (!entry)
+        return MISS;
+    let value = entry.value;
+    if (cache.schema) {
+        const result = await cache.schema["~standard"].validate(value);
+        if (result.issues)
+            return MISS;
+        value = result.value;
+    }
+    const ageMs = Math.max(0, Date.now() - entry.savedAt);
+    if (cache.stale && (await cache.stale({ value, input, ctx, savedAt: entry.savedAt, ageMs }))) {
+        return MISS;
+    }
+    return { hit: true, value, ageMs };
+}
+/** Only ever called after the phase or step has fully succeeded. */
+export async function writeCache(cache, slot, value, mode) {
+    if (mode === "off" || mode === "read-only")
+        return;
+    await cache.store.write(slot, { value, savedAt: Date.now() });
+}
+/** Identifies a phase's entry. Steps hang off their phase to avoid collisions. */
+export const phaseSlot = (phase) => phase;
+export const stepSlot = (phase, step) => `${phase}::${step}`;
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAa,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAEV,eAAe,EACf,WAAW,EAGZ,MAAM,YAAY,CAAC;AA6FpB,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,GAAG,EACvC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GACd,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CAwBtB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAChD,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,GAAG,EACX,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,GAClB,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAiB/B"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA2B,SAAS,EAAa,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAEV,eAAe,EACf,WAAW,EAGZ,MAAM,YAAY,CAAC;AA6FpB,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AASD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,GAAG,EACvC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GACd,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CA2BtB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAChD,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,GAAG,EACX,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,GAClB,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAkB/B"}

package/dist/context.js

@@ -78,9 +78,19 @@ function createTaskList(step, renderer, labels) {
         get: (key) => map[key],
     };
 }
+/** Set (or, given "", clear) the step's persistent title annotation. */
+function annotate(step, renderer, message) {
+    if (message === "")
+        delete step.note;
+    else
+        step.note = message;
+    renderer.refresh();
+}
 export function createStepContext(deps, input, ctx, signal, attempt) {
     const { renderer, step, phaseName } = deps;
-    const emit = (level) => (message) => renderer.log({ level, message });
+    // `step` is a routing hint: renderers that place logs on the step itself
+    // (rather than the scrollback) need to know which one.
+    const emit = (level) => (message) => renderer.log({ level, message }, step);
     return {
         input,
         ctx,
@@ -97,6 +107,7 @@ export function createStepContext(deps, input, ctx, signal, attempt) {
             step.statusText = message;
             renderer.refresh();
         },
+        note: (message) => annotate(step, renderer, message),
         progress: (options) => createProgress(step, renderer, options),
         task: (label) => createTask(step, renderer, label),
         tasks: (labels) => createTaskList(step, renderer, labels),
@@ -112,11 +123,12 @@ export function createRollbackContext(deps, input, ctx, output, error, signal) {
         signal,
         phase: phaseName,
         step: step.name,
-        log: (message) => renderer.log({ level: "warn", message }),
+        log: (message) => renderer.log({ level: "warn", message }, step),
         status(message) {
             step.statusText = message;
             renderer.refresh();
         },
+        note: (message) => annotate(step, renderer, message),
         progress: (options) => createProgress(step, renderer, options),
     };
 }

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAUA,SAAS,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,cAAc,CACrB,IAAe,EACf,QAAkB,EAClB,OAA0D;IAE1D,MAAM,GAAG,GAAkB;QACzB,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC;QACjC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC/D,QAAQ,EAAE,KAAK;KAChB,CAAC;IACF,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC3D,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,CAAC;IAEnB,OAAO;QACL,IAAI,KAAK;YACP,OAAO,GAAG,CAAC,KAAK,CAAC;QACnB,CAAC;QACD,IAAI,KAAK;YACP,OAAO,GAAG,CAAC,KAAK,CAAC;QACnB,CAAC;QACD,MAAM,CAAC,KAAK,EAAE,KAAK;YACjB,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YACvC,IAAI,KAAK,KAAK,SAAS;gBAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;YAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,EAAE,GAAG,CAAC;YACd,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAChD,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QACD,QAAQ,CAAC,KAAK;YACZ,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC/B,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QACD,QAAQ,CAAC,KAAK;YACZ,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;YAClB,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QACD,IAAI;YACF,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YACtB,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC;YACpB,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,IAAe,EAAE,QAAkB;IACpD,MAAM,GAAG,GAAG,CAAC,MAA2B,EAAE,IAAa,EAAQ,EAAE;QAC/D,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,QAAQ,CAAC,OAAO,EAAE,CAAC;IACrB,CAAC,CAAC;IACF,OAAO;QACL,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC;QACrC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;QACvC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;QACpC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC;QACnC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAe,EAAE,QAAkB,EAAE,KAAa;IACpE,MAAM,IAAI,GAAc,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnB,OAAO,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,cAAc,CACrB,IAAe,EACf,QAAkB,EAClB,MAAS;IAET,MAAM,GAAG,GAAG,EAAmC,CAAC;IAChD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAc,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACrD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,GAAG,CAAC,KAAkB,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IACD,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnB,OAAO;QACL,KAAK,EAAE,GAAG;QACV,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;KACvB,CAAC;AACJ,CAAC;AAQD,wEAAwE;AACxE,SAAS,QAAQ,CAAC,IAAe,EAAE,QAAkB,EAAE,OAAe;IACpE,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;;QAChC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,IAAiB,EACjB,KAAS,EACT,GAAQ,EACR,MAAmB,EACnB,OAAe;IAEf,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3C,yEAAyE;IACzE,uDAAuD;IACvD,MAAM,IAAI,GAAG,CAAC,KAAe,EAAE,EAAE,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;IAE9F,OAAO;QACL,KAAK;QACL,GAAG;QACH,MAAM;QACN,OAAO;QACP,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC;QAChB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC;QACxB,MAAM,CAAC,OAAO;YACZ,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;YAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QACD,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC;QACpD,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC;QAC9D,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC;QAClD,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAAiB,EACjB,KAAS,EACT,GAAQ,EACR,MAAW,EACX,KAAc,EACd,MAAmB;IAEnB,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3C,OAAO;QACL,KAAK;QACL,GAAG;QACH,MAAM;QACN,KAAK;QACL,MAAM;QACN,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC;QAChE,MAAM,CAAC,OAAO;YACZ,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;YAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QACD,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC;QACpD,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -4,6 +4,29 @@ export declare class SchemaValidationError extends Error {
     readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
     constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
 }
+/**
+ * A step was declared in a way the script cannot honour — today, a `clean`
+ * naming a key some step reserved through `rollbackKeys`. Thrown by `addStep`,
+ * while the script is being built, long before anything runs.
+ */
+export declare class StepDefinitionError extends Error {
+    readonly step: string;
+    constructor(step: string, message: string);
+}
+/**
+ * Two phases, or two steps within one phase, were given the same name. Thrown
+ * while the script is being built.
+ *
+ * Names are not decoration: they label the frame, they are what `outline()`
+ * reports, and they identify a phase's or step's cache entry. Two units
+ * sharing a name share a slot, which surfaces as wrong data rather than as a
+ * failure — so it is refused up front.
+ */
+export declare class DuplicateNameError extends Error {
+    readonly kind: "phase" | "step";
+    readonly duplicate: string;
+    constructor(kind: "phase" | "step", duplicate: string, message: string);
+}
 /** A step's handler threw. `cause` holds whatever it actually threw. */
 export declare class StepFailedError extends Error {
     readonly phase: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAE3C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC;CAgB1D;AAED,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAO1E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM5C;AAED,4EAA4E;AAC5E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED,+EAA+E;AAC/E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO;CAOhF;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAE3C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC;CAgB1D;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMvE;AAED,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAO1E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM5C;AAED,4EAA4E;AAC5E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED,+EAA+E;AAC/E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO;CAOhF;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/C"}

package/dist/errors.js

@@ -14,6 +14,38 @@ export class SchemaValidationError extends Error {
         this.issues = issues;
     }
 }
+/**
+ * A step was declared in a way the script cannot honour — today, a `clean`
+ * naming a key some step reserved through `rollbackKeys`. Thrown by `addStep`,
+ * while the script is being built, long before anything runs.
+ */
+export class StepDefinitionError extends Error {
+    step;
+    constructor(step, message) {
+        super(message);
+        this.name = "StepDefinitionError";
+        this.step = step;
+    }
+}
+/**
+ * Two phases, or two steps within one phase, were given the same name. Thrown
+ * while the script is being built.
+ *
+ * Names are not decoration: they label the frame, they are what `outline()`
+ * reports, and they identify a phase's or step's cache entry. Two units
+ * sharing a name share a slot, which surfaces as wrong data rather than as a
+ * failure — so it is refused up front.
+ */
+export class DuplicateNameError extends Error {
+    kind;
+    duplicate;
+    constructor(kind, duplicate, message) {
+        super(message);
+        this.name = "DuplicateNameError";
+        this.kind = kind;
+        this.duplicate = duplicate;
+    }
+}
 /** A step's handler threw. `cause` holds whatever it actually threw. */
 export class StepFailedError extends Error {
     phase;

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,oFAAoF;AACpF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,MAAM,CAAwC;IAEvD,YAAY,MAA6C;QACvD,KAAK,CACH,MAAM;aACH,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI;gBACrB,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAChB,MAAM,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAChF;iBACA,IAAI,CAAC,GAAG,CAAC,CAAC;YACb,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QAC5D,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CACd,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,KAAK,CAAS;IACd,IAAI,CAAS;IACb,QAAQ,CAAS;IAE1B,YAAY,KAAa,EAAE,IAAY,EAAE,QAAgB,EAAE,KAAc;QACvE,KAAK,CAAC,SAAS,IAAI,eAAe,KAAK,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IACb,SAAS,CAAS;IAE3B,YAAY,IAAY,EAAE,SAAiB;QACzC,KAAK,CAAC,SAAS,IAAI,qBAAqB,SAAS,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,mBAAmB,MAAM,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,KAAK,CAAS;IACd,IAAI,CAAS;IACb,aAAa,CAAU;IAEhC,YAAY,KAAa,EAAE,IAAY,EAAE,aAAsB,EAAE,KAAc;QAC7E,KAAK,CAAC,iBAAiB,IAAI,eAAe,KAAK,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,KAAK,YAAY,kBAAkB;QACnC,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { Script, script, stepFor, type RunOptions } from "./script.js";
-export { RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
-export type { Awaitable, Merge, PhaseOptions, PhaseStatus, Prettify, ProgressHandle, RetryPolicy, RollbackContext, RollbackReport, RunResult, RunStatus, ScriptOptions, StepContext, StepDef, StepReport, StepStatus, TaskHandle, TaskListHandle, } from "./types.js";
+export { Script, script, stepFor, routineFor, type MountOptions, type Routine, type RunOptions, } from "./script.js";
+export { fileStore, memoryStore } from "./cache.js";
+export { DuplicateNameError, RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepDefinitionError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
+export type { Awaitable, CacheMode, CacheOptions, CacheSource, CacheStore, CachedEntry, CleanField, Cleaned, LogPlacement, Merge, PhaseOptions, PhaseStatus, Prettify, ProgressHandle, RetryPolicy, RollbackContext, RollbackData, RollbackReport, RunResult, RunStatus, ScriptOptions, StaleContext, StepContext, StepDef, StepReport, StepStatus, TaskHandle, TaskListHandle, } from "./types.js";
 export { formatDuration } from "./state.js";
 export { setColorEnabled, isColorEnabled } from "./ui/ansi.js";
 export { palette, symbols } from "./ui/theme.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,KAAK,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,eAAe,EACf,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,OAAO,EACP,YAAY,EACZ,KAAK,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
-export { Script, script, stepFor } from "./script.js";
-export { RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
+export { Script, script, stepFor, routineFor, } from "./script.js";
+export { fileStore, memoryStore } from "./cache.js";
+export { DuplicateNameError, RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepDefinitionError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
 export { formatDuration } from "./state.js";
 export { setColorEnabled, isColorEnabled } from "./ui/ansi.js";
 export { palette, symbols } from "./ui/theme.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAmB,MAAM,aAAa,CAAC;AAEvE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAuBrB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,GAIX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAiCrB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/script.d.ts

@@ -1,8 +1,60 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { Merge, PhaseOptions, RunResult, ScriptOptions, StepDef } from "./types.js";
+import type { Awaitable, CacheMode, CleanField, Cleaned, Merge, PhaseOptions, RunResult, ScriptOptions, StepDef } from "./types.js";
+/**
+ * Keys for the phantom markers on {@link Script} and {@link Routine}. Exported
+ * only because declaration emit has to name them; there is no runtime value
+ * behind either and nothing should import them.
+ */
+export declare const REQUIRES: unique symbol;
+export declare const PRODUCES: unique symbol;
+/**
+ * Phases and steps recorded away from any particular script, ready to be
+ * spliced into one with {@link Script.use}.
+ *
+ * All four parameters are inferred — `In` and `Ctx` from the `routineFor<In,
+ * Ctx>()` call that declared the routine, `Out` and `Reserved` from the steps
+ * it went on to add.
+ */
+export interface Routine<In, Ctx extends object, Out extends object, Reserved extends PropertyKey> {
+    /**
+     * Phantom. `In` and `Ctx` sit in contravariant position here, which is what
+     * makes a mount site prove it already offers at least this much input and
+     * context. Erased at compile time.
+     */
+    readonly [REQUIRES]: (context: {
+        input: In;
+        ctx: Ctx;
+    }) => void;
+    /** Phantom. Carries what the routine contributes so `use` can infer it. */
+    readonly [PRODUCES]: Out;
+    readonly name: string;
+}
+export interface MountOptions {
+    /**
+     * Prefix for the routine's phase names — `"Amazon"` turns `Fetch` into
+     * `Amazon / Fetch`. Required whenever the same routine is mounted twice,
+     * since phase names have to stay unique.
+     */
+    as?: string;
+}
+/**
+ * What a mount feeds its fragment instead of the host's own input — either a
+ * fixed value or a function of the host's input and context, resolved once
+ * when the mount is reached.
+ */
+export type MountInput<In, Ctx, SubIn> = SubIn | ((context: {
+    input: In;
+    ctx: Ctx;
+}) => Awaitable<SubIn>);
 export interface RunOptions {
     /** Cancel the run from the outside. */
     signal?: AbortSignal;
+    /**
+     * What this run may do with the caches the script declares. Default `"on"`.
+     * Wire it to a flag — `cache: argv.includes("--no-cache") ? "off" : "on"` —
+     * to control caching without touching the script.
+     */
+    cache?: CacheMode;
 }
 /**
  * A saga-style script: phases of steps, each step optionally compensating when
@@ -27,10 +79,25 @@ export interface RunOptions {
  *   })
  *   .run({ userId: "u_1" });
  * ```
+ *
+ * The third parameter is inferred too: it collects the keys steps reserved
+ * through `rollbackKeys`, which is how `clean` knows what it may not remove.
  */
-export declare class Script<In = void, Ctx extends object = {}> {
+export declare class Script<In = void, Ctx extends object = {}, Reserved extends PropertyKey = never> {
+    /**
+     * Phantom, erased at compile time. `run` is a *method*, so its parameter
+     * compares bivariantly and `In` would otherwise carry no safety across two
+     * `Script` types — a script needing `{ a, b }` would mount into a host
+     * offering only `{ a }`. A property-position function makes `In`
+     * contravariant, which is what `use()` relies on.
+     */
+    readonly [REQUIRES]: (input: In) => void;
     private readonly options;
     private readonly definition;
+    private readonly reserved;
+    private readonly phaseNames;
+    /** False right after `use()`, so a bare `addStep` cannot land in a fragment. */
+    private openPhase;
     private _schema;
     constructor(options?: ScriptOptions | string);
     /**
@@ -53,25 +120,70 @@ export declare class Script<In = void, Ctx extends object = {}> {
      *   });
      * ```
      */
-    defineInput<TSchema>(schema: StandardSchemaV1<unknown, TSchema>): Script<TSchema, Ctx>;
+    defineInput<TSchema>(schema: StandardSchemaV1<unknown, TSchema>): Script<TSchema, Ctx, Reserved>;
     /** Validate `input` against the schema from `defineInput`, if any. */
     private validateInput;
     /** Open a new phase. Subsequent `addStep` calls land in it. */
-    addPhase(name: string, options?: PhaseOptions<In, Ctx>): Script<In, Ctx>;
+    addPhase(name: string, options?: PhaseOptions<In, Ctx>): Script<In, Ctx, Reserved>;
     /** Open a phase and populate it inside a callback, keeping the type flow. */
-    addPhase<Next extends object>(name: string, build: (script: Script<In, Ctx>) => Script<In, Next>): Script<In, Next>;
-    addPhase<Next extends object>(name: string, options: PhaseOptions<In, Ctx>, build: (script: Script<In, Ctx>) => Script<In, Next>): Script<In, Next>;
+    addPhase<Next extends object, NextReserved extends PropertyKey>(name: string, build: (script: Script<In, Ctx, Reserved>) => Script<In, Next, NextReserved>): Script<In, Next, NextReserved>;
+    addPhase<Next extends object, NextReserved extends PropertyKey>(name: string, options: PhaseOptions<In, Ctx>, build: (script: Script<In, Ctx, Reserved>) => Script<In, Next, NextReserved>): Script<In, Next, NextReserved>;
     /**
      * Append a step to the current phase. Whatever the handler resolves to is
-     * merged into the context and becomes visible to every later step.
+     * merged into the context and becomes visible to every later step; whatever
+     * it lists in `clean` is dropped from both.
+     *
+     * @throws {StepDefinitionError} if `clean` names a key reserved by some
+     * step's `rollbackKeys`.
      */
-    addStep<Out extends object | void>(def: StepDef<In, Ctx, Out>): Script<In, Merge<Ctx, Out>>;
+    addStep<Out extends object | void, const RollbackKeys extends readonly PropertyKey[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: StepDef<In, Ctx, Out, RollbackKeys> & CleanField<Ctx, Reserved, CleanKeys>): Script<In, Cleaned<Merge<Ctx, Out>, CleanKeys[number]>, Reserved | RollbackKeys[number]>;
+    /**
+     * Splice a reusable fragment into this script. Its phases land here in
+     * order, and everything it produced is merged into the context — so the
+     * steps that follow see it, typed, exactly as if they had been written
+     * inline.
+     *
+     * The fragment states what it needs and TypeScript checks it at the mount
+     * site: a routine declared `routineFor<{ name: string }, { hash: string }>()`
+     * refuses to mount into a script whose input lacks `name`, or which has not
+     * produced `hash` yet.
+     *
+     * ```ts
+     * new Script<Input>({ name: "monthly report" })
+     *   .use(fetchChannel)
+     *   .addPhase("Report")
+     *   .addStep({ name: "aggregate", handler: ({ ctx }) => summarise(ctx.orders) });
+     * ```
+     *
+     * A plain {@link Script} mounts too, which is what keeps a reusable pipeline
+     * runnable on its own. Its own {@link ScriptOptions} — rollback mode,
+     * `logPlacement`, `silent` — are ignored in favour of the host's; only its
+     * phases and steps come across.
+     *
+     * @throws {DuplicateNameError} if a phase it brings is already defined here.
+     * Mount the same routine twice by naming each mount with `as`.
+     */
+    use<SubIn, Out extends object, R extends PropertyKey>(routine: Routine<SubIn, Ctx, Out, R>, options: MountOptions & {
+        input: MountInput<In, Ctx, SubIn>;
+    }): Script<In, Merge<Ctx, Out>, Reserved | R>;
+    use<SubIn, Out extends object, R extends PropertyKey>(script: Script<SubIn, Out, R>, options: MountOptions & {
+        input: MountInput<In, Ctx, SubIn>;
+    }): Script<In, Merge<Ctx, Out>, Reserved | R>;
+    use<Out extends object, R extends PropertyKey>(script: Script<In, Out, R>, options?: MountOptions): Script<In, Merge<Ctx, Out>, Reserved | R>;
+    use<Out extends object, R extends PropertyKey>(routine: Routine<In, Ctx, Out, R>, options?: MountOptions): Script<In, Merge<Ctx, Out>, Reserved | R>;
     /** Every step name, in execution order — handy for tests and docs. */
     outline(): Array<{
         phase: string;
         steps: string[];
     }>;
     private currentPhase;
+    /**
+     * Phase names have to be unique: they are what the frame labels, what
+     * `outline()` reports, and — since the cache landed — what identifies a
+     * phase's stored entry. Two phases sharing a name share a cache slot, which
+     * reads as wrong data rather than as an error.
+     */
+    private claimPhaseName;
     run(input: In, runOptions?: RunOptions): Promise<RunResult<Ctx>>;
     /** Retry + timeout wrapper around a single handler invocation. */
     private executeStep;
@@ -93,8 +205,36 @@ export declare class Script<In = void, Ctx extends object = {}> {
  *   handler: async ({ ctx }) => ({ verified: ctx.user.id }),
  * });
  * ```
+ *
+ * `rollbackKeys` works the same here, and the keys it names stay reserved once
+ * the step is handed to `addStep`.
+ */
+export declare function stepFor<In, Ctx extends object = {}>(): <Out extends object | void, const RollbackKeys extends readonly PropertyKey[] = readonly []>(def: StepDef<In, Ctx, Out, RollbackKeys>) => StepDef<In, Ctx, Out, RollbackKeys>;
+/**
+ * Declare phases and steps away from any particular script, then mount them
+ * with {@link Script.use}.
+ *
+ * The two parameters are the *minimum* the fragment needs — the input it
+ * reads, and the context it expects to already exist — exactly as they are for
+ * {@link stepFor}. Whatever it produces flows on into whichever script mounts
+ * it, and any script that cannot satisfy the requirement is a compile error at
+ * the `use()` call, not an `undefined` at run time.
+ *
+ * ```ts
+ * export const fetchChannel = routineFor<{ channel: string }>()("fetch channel", (s) =>
+ *   s
+ *     .addPhase("Fetch")
+ *     .addStep({ name: "authenticate", handler: … })
+ *     .addStep({ name: "pull orders", handler: … })
+ *     .addPhase("Normalize")
+ *     .addStep({ name: "dedupe", handler: … }),
+ * );
+ * ```
+ *
+ * A routine owns whole phases, so phase-level options — `when`, `cache` —
+ * travel with it.
  */
-export declare function stepFor<In, Ctx extends object = {}>(): <Out extends object | void>(def: StepDef<In, Ctx, Out>) => StepDef<In, Ctx, Out>;
+export declare function routineFor<In, Ctx extends object = {}>(): <Out extends object, R extends PropertyKey>(name: string, build: (script: Script<In, Ctx, never>) => Script<In, Out, R>) => Routine<In, Ctx, Out, R>;
 /** Convenience factory so callers can skip `new`. */
 export declare function script<In = void>(options?: ScriptOptions | string): Script<In, {}>;
 //# sourceMappingURL=script.d.ts.map

package/dist/script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../src/script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAI9D,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAIZ,SAAS,EACT,aAAa,EACb,OAAO,EAER,MAAM,YAAY,CAAC;AAqBpB,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,MAAM,GAAG,EAAE;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,OAAO,CAA+B;gBAElC,OAAO,GAAE,aAAa,GAAG,MAAW;IAIhD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC;IAKtF,sEAAsE;YACxD,aAAa;IAO3B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC;IACxE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,SAAS,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,GACnD,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,IAAI,SAAS,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,EAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,GACnD,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC;IAqBnB;;;OAGG;IACH,OAAO,CAAC,GAAG,SAAS,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAK3F,sEAAsE;IACtE,OAAO,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAOpD,OAAO,CAAC,YAAY;IAYd,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,UAAU,GAAE,UAAe,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAoL1E,kEAAkE;YACpD,WAAW;IA8DzB,mDAAmD;YACrC,MAAM;IAsDpB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CA+B3B;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,GAAG,SAAS,MAAM,GAAG,EAAE,MACzC,GAAG,SAAS,MAAM,GAAG,IAAI,EAAE,KAAK,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CACtF;AAED,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAElF"}
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../src/script.ts"],"names":[],"mappings":"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"}