@michaelrwalker/stagehand 0.3.0 → 0.5.0

package/README.md

@@ -303,6 +303,139 @@ per placement.
 `when` returning false marks the step **skipped** — its rollback never runs.
 Phases accept `when` too, which skips all their steps.
 
+## Caching
+
+A phase or a step can reuse what it produced on an earlier run. Point it at a
+store and it stops repeating work:
+
+```ts
+import { Script, fileStore } from "@michaelrwalker/stagehand";
+
+const cache = fileStore("./.stagehand-cache.json");
+
+new Script<Input>({ name: "deploy" })
+  .addPhase("Build", { cache })
+  .addStep({ name: "install", handler: … })
+  .addStep({ name: "compile", handler: … })
+
+  .addPhase("Release")
+  .addStep({ name: "warm CDN", cache, handler: … })
+```
+
+On a hit the work is skipped and the stored value is merged into the context —
+downstream steps see the same keys, at the same types, either way.
+
+**What gets stored.** A phase stores its **delta**: the keys its steps
+contributed, minus anything they `clean`ed. Keys from earlier phases are never
+part of it, so a hit can't overwrite a value this run just computed. A step
+stores exactly what its handler returned.
+
+**There is no key.** The store is the identity. Say when an entry stops being
+good with `stale`, or delete the file:
+
+```ts
+.addPhase("Build", {
+  cache: {
+    store: cache,
+    stale: ({ value, ctx, ageMs }) => ageMs > 3_600_000 || value.sha !== ctx.sha,
+    schema: BuildSchema,   // optional; a value that no longer fits is a miss
+  },
+})
+```
+
+`stale` and `schema` both see the context as it stands when the phase is
+reached, so `ctx` is typed with no annotation. `value` arrives as `unknown` —
+annotate the parameter, or hand over a `schema` and let it narrow. A stored
+value that fails its schema is treated as a **miss**, not an error, which is
+what stops a cache written by an older version of the script from feeding the
+wrong shape into the context.
+
+**Rollback.** Cached work never ran, so its `rollback` can't fire during a
+later unwind — the side effect belongs to the run that wrote the entry and was
+never undone. For the same reason a failure downstream leaves entries alone.
+
+**Per run**, without touching the script:
+
+```ts
+await deploy.run(input, { cache: argv.includes("--no-cache") ? "off" : "on" });
+```
+
+`"on"` (default) reads and writes · `"off"` ignores caching entirely ·
+`"refresh"` runs everything and overwrites · `"read-only"` uses hits but never
+writes.
+
+### Reaching the cache from a step
+
+Every handler and rollback gets a `cache` handle, typed to the cached phases
+declared **before** it:
+
+```ts
+.addPhase("Fetch", { cache: { store } })
+.addStep({ name: "pull orders", handler: … })       // → { orders }
+
+.addPhase("Adjust")
+.addStep({
+  name: "restock",
+  handler: async ({ ctx, cache }) => {
+    await cache.clear("Fetch");                     // next run refetches
+    await cache.write("Fetch", { orders: ctx.orders }, { keepAge: true });
+    const age = await cache.ageOf("Fetch");
+  },
+})
+```
+
+Slot names are checked, not stringly-typed. An uncached phase isn't a slot at
+all, and `as` renames a mounted routine's slots along with its phases — so the
+moment you write `.use(pullChannel, { as: "Amazon" })`, every
+`cache.clear("Fetch")` in the script goes red and offers `"Amazon / Fetch"`
+instead. That's the failure a hand-written string can't catch: it would keep
+compiling and silently address nothing.
+
+Invalidation flows backwards only — a later step can drop an earlier phase's
+entry, not the reverse.
+
+`write` restamps the entry as written *now* unless you pass `keepAge`. Reach
+for it when you are correcting a value rather than refreshing it: restamping
+silently buys another full TTL for data that is exactly as old as it was a
+moment ago, which is the opposite of what you want when the cache is there to
+keep you inside a rate limit.
+
+**Values are typed too.** A slot with a `schema` reads back as the schema's
+output, because that is the one thing actually *checked* against the stored
+JSON. Without a schema the phase's own delta stands in, which is convenient and
+true right up until an entry outlives the code that wrote it. For that case
+`read` returns the value behind a guard:
+
+```
+CacheShapeError: Read "orders.0.date_fixed" from cache slot "Fetch", but the
+stored value has no such property. The entry was probably written before this
+script's shape changed — drop it with cache.clear("Fetch"), or declare a schema
+on the slot to have mismatches rejected on read.
+```
+
+Only reads are trapped; assigning a new property is how you'd patch an entry.
+Missing array indices, `JSON.stringify`, `await` and iteration all behave
+normally. Pass `{ raw: true }` to opt out — do that before putting the value
+into the context, or the guard travels with it into later steps.
+
+**Stores** are three methods, so Redis or S3 is a dozen lines:
+
+```ts
+interface CacheStore {
+  read(slot: string): Awaitable<CachedEntry | undefined>;
+  write(slot: string, entry: CachedEntry): Awaitable<void>;
+  clear(slot: string): Awaitable<void>;
+}
+```
+
+`slot` is derived from the phase or step name so several phases can share one
+store; scripts never write it. `fileStore(path)` keeps every slot in one JSON
+file — a missing, unreadable or corrupt file all read as no cache at all, so
+deleting it is always a valid reset. `memoryStore()` lasts for the process.
+
+A store that throws — unreadable file, full disk, a `stale` predicate with a bug
+— logs a warning and does the work. Caching never decides whether a run passes.
+
 ## Script options
 
 ```ts
@@ -350,9 +483,119 @@ script has actually produced `Ctx` by that point. Dropping a step that needs
 `{ user: User }` into a script that has not loaded a user yet is a compile
 error, not a runtime `undefined`.
 
+## Reusable scripts
+
+`routineFor` does for whole phases what `stepFor` does for one step. Declare a
+fragment once, mount it wherever it fits:
+
+```ts
+// routines/channel.ts
+export const pullChannel = routineFor<{ channel: string; since: string }>()(
+  "pull channel",
+  (script) =>
+    script
+      .addPhase("Fetch", { cache: { store: cache, stale: … } })
+      .addStep({ name: "authenticate", handler: … })
+      .addStep({ name: "pull orders", handler: … })
+      .addPhase("Normalize")
+      .addStep({ name: "dedupe and total", handler: … }),
+);
+```
+
+```ts
+new Script<Input>({ name: "channel sync" })
+  .use(pullChannel)
+  .addPhase("Validation")
+  .addStep({ name: "check totals", handler: ({ ctx }) => … })   // ctx.orderCount, ctx.gross
+
+// months later, a different job entirely
+new Script<ReportInput>({ name: "monthly report" })
+  .use(pullChannel)
+  .addPhase("Report")
+  .addStep({ name: "build summary", handler: ({ ctx }) => … })
+```
+
+The two parameters on `routineFor<In, Ctx>()` are the **minimum** the fragment
+needs — the input it reads, and the context it expects to already exist. Both
+are checked at the `use()` call:
+
+```
+Property 'hash' is missing in type '{}' but required in type '{ hash: string; }'.
+```
+
+A plain `Script` mounts too, which is what keeps a pipeline runnable on its
+own — `pipeline.run(input)` today, `.use(pipeline)` tomorrow. Its own
+`ScriptOptions` (rollback mode, `logPlacement`, `silent`) are ignored in favour
+of the host's; only its phases and steps come across.
+
+**Everything travels with the fragment.** Phase-level `when` and `cache`,
+step-level `retry`, `clean`, `rollback` — a spliced rollback compensates during
+the host's unwind, and keys it reserved through `rollbackKeys` stay reserved in
+the host, so a later `clean` there still can't delete them.
+
+That combines well with caching: mount a routine whose phase caches, and the
+second script to mount it gets the data the first one pulled.
+
+```
+› Fetch
+  ⊙ authenticate  cached
+  ⊙ pull orders  cached
+› Report
+  ✔ build summary (avg 24.50)  263ms
+```
+
+### Giving a mount its own input
+
+A mount can feed its fragment something other than the host's input — which is
+what lets one routine serve two storefronts, each with its own credentials:
+
+```ts
+new Script<{ since: string; amazonKey: string; shopifyKey: string }>({ name: "all channels" })
+  .use(pullChannel, {
+    as: "Amazon",
+    input: ({ input }) => ({ channel: "amazon", since: input.since, apiKey: input.amazonKey }),
+  })
+  .use(pullChannel, {
+    as: "Shopify",
+    input: ({ input }) => ({ channel: "shopify", since: input.since, apiKey: input.shopifyKey }),
+  })
+```
+
+`input` takes a fixed value or a function of `{ input, ctx }`, and may be
+async. It is resolved **once per mount**, when the mount is reached, and every
+phase and step of that fragment sees the result — including its `when`, its
+`cache`, and its rollbacks during an unwind.
+
+With a mapper the host no longer has to match the routine's input shape at all;
+it only has to produce it. TypeScript checks the return value:
+
+```
+Property 'apiKey' is missing in type '{ channel: string; }' but required in type 'ChannelInput'.
+```
+
+Without one, the host's own input must satisfy the routine, as `stepFor` steps
+require.
+
+**Mounting twice** needs `as`, because phase names have to stay unique:
+
+```ts
+.use(pullChannel, { as: "Amazon" })     // → "Amazon / Fetch", "Amazon / Normalize"
+.use(pullChannel, { as: "Shopify" })
+```
+
+Without it you get a `DuplicateNameError` at build time. That rule is not
+routine-specific — two phases anywhere in a script, or two steps within one
+phase, are refused. Names label the frame, are what `outline()` reports, and
+identify a cache entry; two units sharing a name share a slot, which surfaces
+as wrong data rather than as a failure.
+
+A routine owns whole phases, so `addStep` directly after `use()` is refused
+too — open a phase of your own first, rather than quietly appending to a
+fragment someone else's script also mounts.
+
 ## Examples
 
-Seven runnable scripts, each aimed at a different part of the API. Most take a
+Ten runnable scripts, each aimed at a different part of the API. Most take a
 flag to switch between the happy path and the interesting one.
 
 | | |
@@ -363,6 +606,9 @@ flag to switch between the happy path and the interesting one.
 | [`intake.ts`](examples/intake.ts) | `defineInput` with a hand-rolled Standard Schema, plus the full handler UI surface. `-- --bad` to watch validation reject the run, `-- --dirty` for a failing checklist item |
 | [`modular.ts`](examples/modular.ts) | `stepFor` steps living in [`steps/tenancy.ts`](examples/steps/tenancy.ts), shared by two unrelated scripts — the imported rollback compensates in both. `-- --fail` |
 | [`log-placement.ts`](examples/log-placement.ts) | The same script run three times, once per `logPlacement` value, so the difference is visible directly |
+| [`cache.ts`](examples/cache.ts) | A cached `Build` phase and a cached step. Run it twice to watch the second run skip both. `-- --fresh` to rebuild and overwrite |
+| [`invalidate.ts`](examples/invalidate.ts) | `context.cache` from inside a step: correct an entry without refetching, drop one that is beyond saving, and watch the shape guard catch an entry written before the code changed. `-- --patch`, `-- --drop`, `-- --drift` |
+| [`routine.ts`](examples/routine.ts) | One reusable fragment in [`routines/channel.ts`](examples/routines/channel.ts), mounted by a sync script and, months later, a report that maps its own input onto the routine's — and gets the pull from cache. `-- --multi` mounts it twice, one storefront and API key per mount |
 | [`validate.ts`](examples/validate.ts) | The smallest thing that runs: two steps, `rollback: "none"` |
 
 ```
@@ -370,6 +616,8 @@ npm run example:checkout -- --ok
 npm run example:resilience -- --cancel
 npm run example:intake -- --bad
 npm run example:modular -- --fail
+npm run example:invalidate -- --drift
+npm run example:routine -- --multi
 npm run example:log-placement
 ```
 
@@ -378,12 +626,42 @@ npm run example:log-placement
 ```
 npm run build       # emit dist/
 npm test            # node:test suite
-npm run typecheck   # library + examples + tests
+npm run typecheck   # library + examples + tests + scripts
+npm run preflight   # the release gate (add -- --allow-dirty while working)
 npm run example     # the happy path, live
 npm run example:fail
 npm run release     # release-it: version, tag, publish
 ```
 
+## Releasing
+
+[`scripts/preflight.ts`](scripts/preflight.ts) is the gate, and it is written
+with this library — so every release exercises phases, tasks, `note`, `clean`,
+`when` and `retry` on real work:
+
+```
+› Quality
+  ✔ typecheck  1.2s
+  ✔ tests (120 passing in 9 files)  5.1s
+› Package
+  ✔ build  404ms
+  ✔ entry point resolves  0ms
+  ✔ tarball contents (47 files, 66kB)  180ms
+› Registry
+  ✔ version is unpublished  212ms
+```
+
+It checks the working tree is clean, typechecks all four projects separately so
+a failure names the one that broke, runs the suite, then imports `dist/index.js`
+the way a consumer would and asserts the public surface is actually there.
+`npm pack --dry-run` has to contain the entry point, its declarations, LICENSE
+and README — and must not leak `src/`, `test/`, `examples/` or `scripts/`.
+Finally it asks npm whether the version is already published.
+
+release-it runs it from `after:bump`, which is the first point at which
+package.json holds the version being released. A failure aborts before anything
+is committed, tagged or published.
+
 ## TypeScript layout
 
 One config per directory, because editors resolve a file's config by finding

package/dist/cache.d.ts

@@ -0,0 +1,65 @@
+import type { CacheMode, CacheOptions, CacheSource, CacheStore } from "./types.js";
+/** Lives for the lifetime of the process. Useful in tests, and for re-runs. */
+export declare function memoryStore(): CacheStore;
+/**
+ * One JSON file, holding every slot that points at it. Several phases may
+ * share a path safely, and concurrent writes to one path are serialised.
+ *
+ * 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.
+ */
+export declare function fileStore(filePath: string): CacheStore;
+/** `cache: someStore` is shorthand for `cache: { store: someStore }`. */
+export declare function normalizeCache(source: CacheSource | undefined): CacheOptions | undefined;
+export type CacheLookup = {
+    hit: true;
+    value: unknown;
+    ageMs: number;
+} | {
+    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 declare function readCache(cache: CacheOptions, slot: string, input: unknown, ctx: unknown, mode: CacheMode): Promise<CacheLookup>;
+/** Only ever called after the phase or step has fully succeeded. */
+export declare function writeCache(cache: CacheOptions, slot: string, value: unknown, mode: CacheMode): Promise<void>;
+/** Identifies a phase's entry. Steps hang off their phase to avoid collisions. */
+export declare const phaseSlot: (phase: string) => string;
+export declare const stepSlot: (phase: string, step: string) => string;
+/**
+ * Wrap a value read back from a store so that touching a field it does not
+ * have throws {@link CacheShapeError} instead of yielding `undefined`.
+ *
+ * Only reads are trapped. Assigning a new property is how you'd legitimately
+ * patch an entry before writing it back, so it is left alone — the lie is
+ * always on the read side, where the type promised something the JSON lacks.
+ *
+ * Absent array indices pass through too: `orders[9]` on a short list is
+ * ordinary JavaScript, not a shape mismatch.
+ */
+export declare function guardShape<T>(value: T, slot: string, path?: string): T;
+/** Which store backs each slot, and whether that slot validates on read. */
+export interface SlotBinding {
+    store: CacheStore;
+    schema: boolean;
+}
+/**
+ * Build the `cache` handle a handler sees. Slots it does not know about are
+ * already unreachable through the types; at runtime they throw rather than
+ * silently doing nothing, which is what a plain `store.clear("typo")` does.
+ */
+export declare function createCacheHandle(slots: Map<string, SlotBinding>): {
+    read(slot: string, options?: {
+        raw?: boolean;
+    }): Promise<unknown>;
+    write(slot: string, value: unknown, options?: {
+        keepAge?: boolean;
+    }): Promise<void>;
+    clear(slot: string): Promise<void>;
+    ageOf(slot: string): Promise<number | undefined>;
+};
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EAEX,MAAM,YAAY,CAAC;AAMpB,+EAA+E;AAC/E,wBAAgB,WAAW,IAAI,UAAU,CAWxC;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAoEtD;AAgBD,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAMxF;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,GAAG,EAAE,KAAK,CAAA;CAAE,CAAC;AAInB;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAED,oEAAoE;AACpE,wBAAsB,UAAU,CAC9B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,kFAAkF;AAClF,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,MAAe,CAAC;AAC1D,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,MAA6B,CAAC;AAqBrF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,CAAC,CAelE;AAMD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG;IAClE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAClD,CAoCA"}

package/dist/cache.js

@@ -0,0 +1,251 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { CacheShapeError, StepDefinitionError } from "./errors.js";
+/* -------------------------------------------------------------------------- */
+/* 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);
+        },
+    };
+}
+/**
+ * In-process write queues, keyed by resolved path so two `fileStore` calls on
+ * the same file share one.
+ *
+ * Every write is a read-modify-write of the whole file, which is only correct
+ * if writes to that file never overlap. They otherwise lose each other's slots
+ * and race on the temp file. Cross-process safety is out of scope: two `node`
+ * processes writing one cache file can still interleave.
+ */
+const writeQueues = new Map();
+let tempCounter = 0;
+function serialize(key, task) {
+    const next = (writeQueues.get(key) ?? Promise.resolve()).then(task, task);
+    // A failed write must not poison the writes queued behind it.
+    writeQueues.set(key, next.then(() => undefined, () => undefined));
+    return next;
+}
+/**
+ * One JSON file, holding every slot that points at it. Several phases may
+ * share a path safely, and concurrent writes to one path are serialised.
+ *
+ * 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.
+ */
+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. The temp name
+    // carries a counter as well as the pid — the pid alone is shared by every
+    // write in the process, which is exactly how concurrent writes used to
+    // rename each other's files out from under themselves.
+    const writeAll = async (data) => {
+        await mkdir(dirname(target), { recursive: true });
+        const payload = `${JSON.stringify(data, null, 2)}\n`;
+        const temp = `${target}.${process.pid}.${(tempCounter += 1)}.tmp`;
+        try {
+            await writeFile(temp, payload, "utf8");
+            try {
+                await rename(temp, target);
+            }
+            catch (error) {
+                // Windows, antivirus, editors and file watchers can all hold the
+                // destination open and refuse the atomic swap. Writing in place gives
+                // up atomicity rather than the write.
+                const code = error.code;
+                if (code !== "EPERM" && code !== "EACCES" && code !== "EBUSY" && code !== "EEXIST") {
+                    throw error;
+                }
+                await writeFile(target, payload, "utf8");
+            }
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    };
+    const update = (mutate) => serialize(target, async () => {
+        const data = await readAll();
+        if (!mutate(data))
+            return;
+        await writeAll(data);
+    });
+    return {
+        async read(slot) {
+            const entry = (await readAll())[slot];
+            return isEntry(entry) ? entry : undefined;
+        },
+        write(slot, entry) {
+            return update((data) => {
+                data[slot] = entry;
+                return true;
+            });
+        },
+        clear(slot) {
+            return update((data) => {
+                if (!Object.hasOwn(data, slot))
+                    return false;
+                delete data[slot];
+                return true;
+            });
+        },
+    };
+}
+/** 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}`;
+/* -------------------------------------------------------------------------- */
+/* Shape guard                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Properties every JavaScript runtime reaches for on an arbitrary object.
+ * Trapping them breaks `await` (which probes `then`), `JSON.stringify`,
+ * `console.log` and template interpolation — so they pass straight through.
+ */
+const PASSTHROUGH = new Set([
+    "then",
+    "toJSON",
+    "constructor",
+    "valueOf",
+    "toString",
+    "inspect",
+    "length",
+]);
+/**
+ * Wrap a value read back from a store so that touching a field it does not
+ * have throws {@link CacheShapeError} instead of yielding `undefined`.
+ *
+ * Only reads are trapped. Assigning a new property is how you'd legitimately
+ * patch an entry before writing it back, so it is left alone — the lie is
+ * always on the read side, where the type promised something the JSON lacks.
+ *
+ * Absent array indices pass through too: `orders[9]` on a short list is
+ * ordinary JavaScript, not a shape mismatch.
+ */
+export function guardShape(value, slot, path = "") {
+    if (value === null || typeof value !== "object")
+        return value;
+    return new Proxy(value, {
+        get(target, key, receiver) {
+            const actual = Reflect.get(target, key, receiver);
+            if (typeof key === "symbol" || PASSTHROUGH.has(key))
+                return actual;
+            const isIndex = Array.isArray(target) && /^(0|[1-9]\d*)$/.test(key);
+            const known = Object.hasOwn(target, key) || key in (Object.getPrototypeOf(target) ?? {});
+            if (!isIndex && !known)
+                throw new CacheShapeError(slot, path ? `${path}.${key}` : key);
+            return guardShape(actual, slot, path ? `${path}.${key}` : key);
+        },
+    });
+}
+/**
+ * Build the `cache` handle a handler sees. Slots it does not know about are
+ * already unreachable through the types; at runtime they throw rather than
+ * silently doing nothing, which is what a plain `store.clear("typo")` does.
+ */
+export function createCacheHandle(slots) {
+    const bindingFor = (slot) => {
+        const binding = slots.get(slot);
+        if (!binding) {
+            const known = [...slots.keys()].map((name) => `"${name}"`).join(", ") || "none";
+            throw new StepDefinitionError(slot, `No cached phase named "${slot}" has been declared before this step. Known slots: ${known}.`);
+        }
+        return binding;
+    };
+    return {
+        async read(slot, options) {
+            const binding = bindingFor(slot);
+            const entry = await binding.store.read(slot);
+            if (!entry)
+                return undefined;
+            // A slot with a schema was validated on the way in, so its type is
+            // already backed by a check; only the inferred kind needs guarding.
+            if (options?.raw || binding.schema)
+                return entry.value;
+            return guardShape(entry.value, slot);
+        },
+        async write(slot, value, options) {
+            const store = bindingFor(slot).store;
+            const previous = options?.keepAge ? await store.read(slot) : undefined;
+            await store.write(slot, { value, savedAt: previous?.savedAt ?? Date.now() });
+        },
+        async clear(slot) {
+            await bindingFor(slot).store.clear(slot);
+        },
+        async ageOf(slot) {
+            const entry = await bindingFor(slot).store.read(slot);
+            return entry ? Math.max(0, Date.now() - entry.savedAt) : undefined;
+        },
+    };
+}
+//# 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

@@ -1,3 +1,4 @@
+import type { CacheHandle } from "./types.js";
 import type { StepState } from "./state.js";
 import type { Renderer } from "./ui/renderer.js";
 import type { RollbackContext, StepContext } from "./types.js";
@@ -5,6 +6,8 @@ export interface ContextDeps {
     renderer: Renderer;
     step: StepState;
     phaseName: string;
+    /** Backs `context.cache`; slots declared before the current step. */
+    cache: CacheHandle<Record<string, unknown>>;
 }
 export declare function createStepContext<In, Ctx>(deps: ContextDeps, input: In, ctx: Ctx, signal: AbortSignal, attempt: number): StepContext<In, Ctx>;
 export declare function createRollbackContext<In, Ctx, Out>(deps: ContextDeps, input: In, ctx: Ctx, output: Out, error: unknown, signal: AbortSignal): RollbackContext<In, Ctx, Out>;