@michaelrwalker/stagehand 0.2.0 → 0.4.0

package/README.md

@@ -6,6 +6,7 @@ A fully typesafe, saga-style script framework for TypeScript, with a live termin
 - **Phases** are a collection of **steps**.
 - **Steps** have a `handler` and an optional `rollback` that fires when a *later* step fails.
 - Whatever a handler returns is merged into a **typed context** that every later step can read.
+- A step can `clean` keys it is done with, and a `rollback` declares the keys it needs.
 - Zero runtime dependencies. Live rendering on a TTY, plain line output in CI.
 
 ```ts
@@ -27,8 +28,9 @@ const result = await new Script<{ service: string }>({ name: "deploy" })
 
       return { uploadId: await upload(ctx.sha, bar) };
     },
-    rollback: async ({ output }) => cdn.delete(output.uploadId),
-    //                  ^ typed as { uploadId: string }
+    rollbackKeys: ["sha"],
+    rollback: async ({ ctx, output }) => cdn.delete(output.uploadId, ctx.sha),
+    //                  ^ { sha: string }   ^ typed as { uploadId: string }
   })
   .run({ service: "api" });
 
@@ -46,7 +48,7 @@ if (result.ok) result.ctx.uploadId; // string
      ✔ check permissions                                                   517ms
 
   ⠸ Build                                                                   17.7s
-     ✔ install dependencies                                                 14.4s
+     ✔ install dependencies (428 packages)                                  14.4s
      ⠸ compile bundle  › transform                                           3.3s
        ▕██████████████░░░░░░░░░░▏  58%  412/710  src/router.ts
        ✔ typecheck
@@ -86,6 +88,47 @@ Reaching for a key a previous step did not produce is a compile error, as is
 reading the wrong shape in a `rollback`. A handler that returns nothing leaves
 the context unchanged.
 
+## Cleaning the context
+
+If a step produces — or receives — data that later steps do not need, listing
+those keys in `clean` deletes them from the context at runtime **and** removes
+them from the type that flows on:
+
+```ts
+new Script<{ password: string; email: string }>({ name: "signup" })
+  .addStep({
+    name: "read input",
+    handler: ({ input }) => ({ ...input }),
+  })
+  .addStep({
+    name: "hash",
+    handler: async ({ ctx }) => ({ hash: await hashIt(ctx.password) }),
+    clean: ["password"],   // not needed past this point
+  })
+  .addStep({
+    name: "persist",
+    handler: ({ ctx }) => {
+      ctx.hash;      // string
+      ctx.email;     // string
+      ctx.password;  // compile error — cleaned away
+    },
+  });
+```
+
+Rules:
+
+- Keys are checked against the context as it stands *entering* that step — an
+  unknown key is a compile error, and the editor autocompletes the valid ones.
+  A step cannot clean a key it produces itself; that key does not exist yet
+  when `clean` is read.
+- A key reserved by any step's `rollbackKeys` can never be cleaned, by that
+  step or any later one. Trying to throws `StepDefinitionError` from `addStep`,
+  while the script is being built, before anything runs.
+- `clean` is part of the declared shape, not of the work, so it applies even
+  when the step is skipped by `when` — runtime and types never disagree.
+- A step's own `output` is kept separately and is never cleaned, so its
+  `rollback` still sees everything the handler returned.
+
 ## Input from a schema
 
 `In` doesn't have to be written by hand either. `defineInput` takes any
@@ -122,6 +165,45 @@ A rollback that throws is recorded in `result.rollbacks` and surfaced in the
 summary; it never masks the original error, and the remaining rollbacks still
 run.
 
+### What a rollback can see
+
+A rollback always gets its own step's `output` in full. It gets **no context at
+all** by default — it has to ask, via `rollbackKeys`. Asking does two things: it
+narrows `ctx` inside the rollback to exactly those keys, and it reserves them,
+so neither that step nor any later one can `clean` them away. Whatever the
+rollback declared is therefore guaranteed to still be there if it ever runs.
+
+```ts
+new Script<{ accountId: string; amount: number }>({ name: "charge" })
+  .addStep({ name: "read input", handler: ({ input }) => ({ ...input }) })
+  .addStep({
+    name: "reserve funds",
+    handler: async ({ ctx }) => ({ reservationId: await reserve(ctx.accountId, ctx.amount) }),
+    rollbackKeys: ["accountId", "reservationId"],
+    rollback: async ({ ctx }) => {
+      // ctx is { accountId: string; reservationId: string } — and nothing else
+      await release(ctx.accountId, ctx.reservationId);
+    },
+  })
+  .addStep({
+    name: "charge card",
+    handler: () => {
+      throw new Error("payment gateway timeout");
+    },
+  });
+```
+
+`rollbackKeys` accepts the step's incoming context keys and its own output keys;
+anything else is a compile error. Cleaning a reserved key is a compile error
+too, and throws `StepDefinitionError` at build time:
+
+```ts
+script
+  .addStep({ name: "one", handler: () => {}, rollbackKeys: ["a"], rollback: async () => {} })
+  .addStep({ name: "two", handler: () => {}, clean: ["a"] });
+  //                                          ^ StepDefinitionError: reserved by rollbackKeys
+```
+
 ## The handler surface
 
 Every handler receives one object:
@@ -132,14 +214,75 @@ Every handler receives one object:
 | `ctx` | everything earlier steps produced, fully typed |
 | `signal` | aborts on timeout, Ctrl-C, or an external signal |
 | `attempt` | 1-based, useful with `retry` |
-| `log` / `info` / `warn` / `error` / `success` | permanent lines above the live frame |
-| `status(text)` | transient one-liner beside the step |
+| `log` / `info` / `warn` / `error` / `success` | a line, placed per `logPlacement` (default: permanent, above the live frame) |
+| `status(text)` | transient one-liner beside the step, cleared when it settles |
+| `note(text)` | annotates the step title — `(400 rows found)` — and stays |
 | `progress({ total, label })` | a progress bar → `update` / `increment` / `setTotal` / `done` |
 | `task(label)` | one nested checklist item → `succeed` / `fail` / `skip` |
 | `tasks([...] as const)` | a whole checklist, keyed for typed lookup |
 
-`rollback` receives the same, plus `output` (that step's own return value) and
-`error` (what triggered the unwind).
+`rollback` receives `input`, `signal`, `phase`, `step`, `log`, `status`, `note`
+and `progress`, plus `output` (that step's own return value) and `error` (what
+triggered the unwind). Its `ctx` holds only the keys named in `rollbackKeys`.
+
+### `status` vs `note`
+
+Both write next to the step name, and they differ in lifetime. `status` is
+scratch space for a step in flight — it is wiped the moment the step settles.
+`note` is part of the title: it is written once and stays on the finished line,
+which is where a count, a size, or an id belongs.
+
+```ts
+.addStep({
+  name: "query database",
+  handler: async ({ status, note }) => {
+    status("scanning");            // ⠸ query database  › scanning
+    const rows = await db.all(sql);
+    note(`${rows.length} rows found`);
+    return { rows };
+  },
+})
+// ✔ query database (400 rows found)                                    1.2s
+```
+
+Calling `note` again replaces the text; `note("")` removes it. Both renderers
+show it — the live frame in the title, the CI renderer on the step's line.
+
+## Log placement
+
+By default, `log`/`info`/`warn`/`error`/`success` write a permanent line above
+the whole frame — the complete record for the run, in order. `logPlacement`
+moves them somewhere more local instead:
+
+```ts
+new Script({ name: "checkout", logPlacement: "step" })
+```
+
+| `logPlacement` | where it lands |
+| --- | --- |
+| `"scrollback"` (default) | a permanent line above the frame — the full run, in order |
+| `"step"` | nested under the step that logged it, beside its tasks and progress bar |
+| `"bottom"` | a rolling tail of the most recent lines, below the whole phase tree |
+
+```
+  ✖ Main                                                                  320ms
+     ✔ reserve inventory                                                  320ms
+       • checked warehouse A          ← "step": nested where it happened
+       • checked warehouse B
+     ✖ boom                                                                 0ms
+       boom
+```
+
+`"step"` and `"bottom"` both keep only the most recent few lines — they trade
+completeness for locality, which is exactly what makes a rollback's `log()`
+land next to the step it is undoing instead of scrolling past at the top.
+Reach for `"scrollback"` when the log is the thing you need to still have once
+the run is over. Only the live renderer honours this: the plain/CI renderer is
+already sequential, so every placement just prints each line immediately, in
+order, which is already both complete and in place.
+
+Run `npm run example:log-placement` to see the same script three times, once
+per placement.
 
 ## Step options
 
@@ -150,6 +293,8 @@ Every handler receives one object:
   when: ({ input, ctx }) => input.env === "production",
   retry: { attempts: 3, delayMs: (attempt) => attempt * 250, retryIf: isTransient },
   timeoutMs: 30_000,
+  clean: ["draftId"],          // drop from the context once this step settles
+  rollbackKeys: ["tagName"],   // the context keys `rollback` needs, and reserves
   handler,
   rollback,
 })
@@ -158,6 +303,85 @@ Every handler receives one object:
 `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.
+
+**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
@@ -169,6 +393,7 @@ new Script<Input>({
   plain: undefined,      // force the CI renderer; default auto-detects a TTY
   silent: false,
   handleSignals: true,   // Ctrl-C aborts and compensates; a second one gives up
+  logPlacement: "scrollback", // "scrollback" | "step" | "bottom"
 })
 ```
 
@@ -191,90 +416,185 @@ type RunResult<Ctx> =
 export const verifyId = stepFor<Input, { user: User }>()({
   name: "verify id",
   handler: async ({ ctx }) => ({ verified: ctx.user.id }),
+  rollbackKeys: ["verified"],
+  rollback: async ({ ctx }) => unverify(ctx.verified),
 });
 ```
 
-## Scripts
+`rollbackKeys` narrows the rollback here exactly as it does inline, and the keys
+stay reserved once the step is handed to `addStep`.
 
+`addStep` is where the requirement is enforced: TypeScript checks that the
+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: … }),
+);
 ```
-npm run build       # emit dist/
-npm test            # node:test suite
-npm run typecheck   # library + examples + tests + scripts
-npm run example     # the happy path, live
-npm run example:fail
-npm run release     # dry run of the publish pipeline
+
+```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 }) => … })
 ```
 
-## TypeScript layout
+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:
 
-One config per directory, because editors resolve a file's config by finding
-the nearest `tsconfig.json` — a non-standard filename like `tsconfig.foo.json`
-is invisible to them, so the IDE and the CLI disagree.
+```
+Property 'hash' is missing in type '{}' but required in type '{ hash: string; }'.
+```
 
-| Config | Covers | Why it differs |
-| --- | --- | --- |
-| `tsconfig.json` | `src` | The library. `noEmit`, strict. |
-| `tsconfig.build.json` | `src` | The only config that emits `dist/`. |
-| `examples/tsconfig.json` | `examples` | Imports the built `dist/`. |
-| `test/tsconfig.json` | `test` | Same. |
-| `scripts/tsconfig.json` | `scripts` | Adds `allowImportingTsExtensions`. |
+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.
 
-Only `scripts/` needs that last flag. Node's type stripping does not rewrite
-import extensions, so a script importing a sibling script must write
-`./exec.ts` rather than `./exec.js`. The flag cannot go in the root config:
-`tsconfig.build.json` extends it and sets `noEmit: false`, and TypeScript
-rejects `allowImportingTsExtensions` unless `noEmit` or `emitDeclarationOnly`
-is set (TS5096).
+**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
+```
 
-## The release pipeline
+### Giving a mount its own input
 
-`scripts/release.ts` builds and publishes this package, and is itself written
-with this framework — the pipeline is the integration test.
+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 }),
+  })
 ```
-npm run release                              # dry run; mutates nothing
-npm run release -- --simulate-failure        # rehearse the rollback path
-npm run release -- --publish                 # for real
-npm run release -- --publish --bump minor
-npm run release -- --publish --version 1.0.0 --tag next
+
+`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'.
 ```
 
-| Phase | Steps |
-| --- | --- |
-| Preflight | read manifest · authenticate npm · inspect git · resolve version · check registry |
-| Verify | typecheck · run tests |
-| Package | write version · clean dist · build · verify artifacts · audit tarball |
-| Publish | tag release · push tag · publish to npm |
+Without one, the host's own input must satisfy the routine, as `stepFor` steps
+require.
 
-Three steps compensate, and the ordering is deliberate — `publish to npm` is
-last, so a failure anywhere *before* it unwinds everything and nothing reaches
-the registry:
+**Mounting twice** needs `as`, because phase names have to stay unique:
 
-| Step | Rollback |
-| --- | --- |
-| `write version` | restore the previous version in package.json |
-| `clean dist` | rebuild from source |
-| `tag release` | delete the local tag |
-| `push tag` | delete the remote tag |
-| `publish to npm` | `npm deprecate` — a published version cannot be recalled |
+```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.
 
-`--simulate-failure` performs the local mutations and then fails at the publish
-step. Nothing leaves the machine, and you get to watch the unwind:
+## Examples
+
+Nine 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.
+
+| | |
+| --- | --- |
+| [`deploy.ts`](examples/deploy.ts) | The tour: phases, progress bars, checklists, retry, `note`, `clean`, rollback. `npm run example`, `npm run example:fail` |
+| [`checkout.ts`](examples/checkout.ts) | Saga semantics end to end — three mutations, three compensations, a secret dropped with `clean`, and `logPlacement: "step"` nesting each rollback's log under the step it undoes. `-- --ok` for the happy path |
+| [`resilience.ts`](examples/resilience.ts) | `retry` with backoff, `retryIf` refusing to retry a 401, `timeoutMs` on a hung step, and an external `AbortSignal`. `-- --timeout`, `-- --fatal`, `-- --cancel` |
+| [`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 |
+| [`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"` |
 
 ```
-  ✖ publish to npm  0ms  simulated publish failure (--simulate-failure)
-    ▲ deleted local tag v0.2.0
-    ▲ dist rebuilt from source
-    ▲ package.json version restored to 0.1.0
+npm run example:checkout -- --ok
+npm run example:resilience -- --cancel
+npm run example:intake -- --bad
+npm run example:modular -- --fail
+npm run example:routine -- --multi
+npm run example:log-placement
+```
+
+## npm scripts
 
-  ✖ Failed at Publish › publish to npm after 8.1s
-  ↺ Rolled back 3 steps
 ```
+npm run build       # emit dist/
+npm test            # node:test suite
+npm run typecheck   # library + examples + tests
+npm run example     # the happy path, live
+npm run example:fail
+npm run release     # release-it: version, tag, publish
+```
+
+## TypeScript layout
 
-Other things it checks: a scoped package without `publishConfig.access`
-(`"public"`) would be published as restricted, so preflight refuses; the tarball
-is audited path-by-path against an allowlist so `src/` can never leak; and the
-version is checked against the registry before any work is done.
+One config per directory, because editors resolve a file's config by finding
+the nearest `tsconfig.json` — a non-standard filename like `tsconfig.foo.json`
+is invisible to them, so the IDE and the CLI disagree.
+
+| Config | Covers | Why it differs |
+| --- | --- | --- |
+| `tsconfig.json` | `src` | The library. `noEmit`, strict. |
+| `tsconfig.build.json` | `src` | The only config that emits `dist/`. |
+| `examples/tsconfig.json` | `examples` | Imports the built `dist/`; adds `allowImportingTsExtensions`. |
+| `test/tsconfig.json` | `test` | Same, without the flag. |
+
+Only `examples/` needs that flag, and only because `modular.ts` imports a
+sibling: Node's type stripping does not rewrite import extensions, so the
+import has to say `./steps/tenancy.ts` rather than `./steps/tenancy.js`. The
+flag cannot go in the root config — `tsconfig.build.json` extends it and sets
+`noEmit: false`, and TypeScript rejects `allowImportingTsExtensions` unless
+`noEmit` or `emitDeclarationOnly` is set (TS5096).
 
 ## Rendering notes
 

package/dist/cache.d.ts

@@ -0,0 +1,33 @@
+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.
+ *
+ * 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 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;
+//# 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":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EAEX,MAAM,YAAY,CAAC;AAMpB,+EAA+E;AAC/E,wBAAgB,WAAW,IAAI,UAAU,CAWxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAuCtD;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"}