@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui-surface.ts

@@ -0,0 +1,451 @@
+// Author-facing types for `ui:` on createApp. Authors declare pages and
+// widgets here; renders are bundled separately for the Home iframe and
+// loaders/actions become a JSON manifest Home can read after evaluate.
+
+import type {
+  QueryClient,
+  UseMutationResult,
+  UseQueryOptions,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import type { ZodType } from "zod";
+import type { IconName } from "./ui/components/icons.tsx";
+import type { Ref } from "./ref.ts";
+import type { InferConfigSchema, SurfaceConfigSchema } from "./types.ts";
+
+export type { IconName, SurfaceConfigSchema };
+
+/**
+ * The resolved config object a surface's `configSchema` produces — each
+ * `r.input.*` leaf collapsed to its runtime value (text → string, number →
+ * number, boolean → boolean, enum → the union). Annotate a file-based loader's
+ * `request(state, config)` with `SurfaceConfig<typeof configSchema>` so `config`
+ * is typed the same way the inline `widget()`/`page()` wrappers infer it.
+ */
+export type SurfaceConfig<T extends SurfaceConfigSchema> = InferConfigSchema<T>;
+
+type InferInput<S> = S extends ZodType<infer T> ? T : never;
+type InferOutput<S> = S extends ZodType<infer T> ? T : never;
+
+/**
+ * What a loader/action's `request(state, config)` returns: the HTTP call
+ * to make against the surface's container. `service`/`port` are NOT here
+ * — those are the grant boundary (which container the app may reach), so
+ * they stay static on the loader and Home-controlled. This is only the
+ * *shape* of the call: verb, path, and where the input rides (query
+ * and/or body — a request can use both).
+ *
+ * A loader's `request` may also return `null`, meaning "not ready yet"
+ * (the state doesn't yet have what this call needs). `null` = lazy/idle;
+ * a shape = runnable. That's the whole eager-vs-lazy signal.
+ */
+export type RequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface RequestShape {
+  method: RequestMethod;
+  path: string;
+  /** Encoded onto the URL query string. Flat scalars. */
+  query?: Record<string, string | number | boolean>;
+  /** JSON body. Dropped on GET (which has none). */
+  body?: unknown;
+}
+
+/**
+ * An action mutates, so its request is never a GET: GET carries no body,
+ * and `mutate(input)`'s payload rides `body`. Narrowing the method here
+ * makes a GET action — which would silently drop its input at the worker
+ * proxy — a compile error at authoring time.
+ */
+export interface ActionRequestShape extends Omit<RequestShape, "method"> {
+  method: Exclude<RequestMethod, "GET">;
+}
+
+/**
+ * One worker's answer to a fanned-out call, tagged with who gave it.
+ *
+ * On a system app a call goes to every worker the app runs on,
+ * so every response has an origin. The origin rides *on* the response
+ * rather than in a parallel array because a merge that filters or
+ * reorders would silently desync from one — and a mis-attributed row
+ * looks exactly like a correct one. Wrapping makes that unrepresentable.
+ *
+ * `data` is the container's response, already validated against the
+ * loader's `outputSchema`: the schema describes what the container
+ * returns, and never sees this envelope.
+ */
+export interface WorkerResult<T> {
+  data: T;
+  /** Short slug of the worker that answered (`w1`, `w17`) — `worker.id` at eval. */
+  workerId: string;
+}
+
+/**
+ * The render fn's first arg. `loaders.{name}` / `actions.{name}` are
+ * prebuilt handles typed off the surface's loader/action keys, so
+ * authors get autocomplete matching what they declared. The render fn
+ * calls no hooks itself — the runtime builds every handle up front (and
+ * Home prefills the eager ones), so `loaders.X.data` is already present
+ * on first paint for a loader whose `request` returns a shape at mount.
+ *
+ * `state` / `setState` are the widget's own live UI state (shared across
+ * its loaders); `config` is the surface's resolved settings (set outside
+ * the widget). A loader's `request(state, config)` reads both.
+ */
+export interface RenderApi<
+  // deno-lint-ignore no-explicit-any
+  TLoaders extends Record<string, Loader<any, any, any>> = Record<string, Loader>,
+  // deno-lint-ignore no-explicit-any
+  TActions extends Record<string, Action<any, any, any>> = Record<string, Action>,
+  TState = unknown,
+  TConfig = unknown,
+> {
+  loaders: { [K in keyof TLoaders]: LoaderHandle<TLoaders[K]> };
+  actions: { [K in keyof TActions]: ActionHandle<TActions[K]> };
+  /** The widget's live UI state. Read-only here; mutate via `setState`. */
+  state: TState;
+  /** Patch the widget's state; re-keys every loader whose request depends on it. */
+  setState: (patch: Partial<TState>) => void;
+  /** Reset the widget's state to the `stateSchema` default (its seed). */
+  reset: () => void;
+  /** The surface's resolved config (settings set outside the widget). */
+  config: TConfig;
+  /**
+   * The surface's tanstack-query `QueryClient`. Use it for cross-loader
+   * cache work: `queryClient.invalidateQueries({ queryKey: ["loader", "stats"] })`
+   * to refetch every subscriber of a loader, prefetch a loader before
+   * rendering, or read a cached value out of band. For the common
+   * "refetch this one loader" case, the loader handle exposes `refetch`
+   * directly — reach for `queryClient` only when one handle isn't the
+   * right scope.
+   *
+   * Loader queries are keyed as `["loader", name, request]`.
+   */
+  queryClient: QueryClient;
+}
+
+/**
+ * The type of a surface's default-exported render component when a surface
+ * is authored as a standalone `pages/*.tsx` / `widgets/*.tsx` module rather
+ * than inline. `realm-sdk build` stitches each module's named exports
+ * (`title`, `icon`, `stateSchema`, `configSchema`, `loaders`, `actions`,
+ * `cols`/`rows`) plus this default render into the inline `ui:` block on
+ * `createApp`.
+ *
+ * Type the default export
+ * `Props<typeof loaders, typeof actions, typeof stateSchema, typeof configSchema>`
+ * so `loaders.{name}` / `actions.{name}` / `state` / `config` are typed off
+ * this file's own exports — the same inference the inline `page()` /
+ * `widget()` wrappers give.
+ */
+export type Props<
+  // deno-lint-ignore no-explicit-any
+  TLoaders extends Record<string, Loader<any, any, any>> = Record<string, Loader>,
+  // deno-lint-ignore no-explicit-any
+  TActions extends Record<string, Action<any, any, any>> = Record<string, Action>,
+  TState extends ZodType = ZodType,
+  TConfig extends SurfaceConfigSchema = SurfaceConfigSchema,
+  // deno-lint-ignore no-explicit-any
+> = (api: RenderApi<TLoaders, TActions, InferOutput<TState>, InferConfigSchema<TConfig>>) => any;
+
+/**
+ * The `refetchInterval` knob authors set on a loader *definition* (it
+ * rides the bundle, so a function form survives — the JSON manifest and
+ * QuickJS can't carry a function). Picked 1:1 from tanstack-query's
+ * `UseQueryOptions` so authors can look up `refetchInterval` in tanstack
+ * docs and the type matches exactly.
+ */
+export type LoaderQueryOptions = Pick<UseQueryOptions, "refetchInterval">;
+
+/**
+ * A loader's `data` is the shape it hands the render fn. For a merge loader
+ * that's `merge`'s return type — which may differ from the per-worker
+ * `outputSchema` (folding N per-worker responses into one merged view). For a
+ * plain loader it's `InferOutput<outputSchema>`, which is also what `merge`'s
+ * type defaults to, so both resolve through the same read of `merge`'s return.
+ */
+type LoaderData<
+  // deno-lint-ignore no-explicit-any
+  L extends Loader<any, any, any, any>,
+  // deno-lint-ignore no-explicit-any
+> =
+  NonNullable<L["merge"]> extends (...args: any[]) => infer M ? M : InferOutput<L["outputSchema"]>;
+
+/**
+ * A loader handle: the full tanstack-query `UseQueryResult` (so authors
+ * get `data` / `isLoading` / `error` / `refetch` / `isFetching` /
+ * `status` / `dataUpdatedAt`, everything tanstack docs cover).
+ *
+ * There's no per-loader `setState`/`reset` — a loader has no input of its
+ * own. It reads the *widget's* `state` via its `request`, so you drive it
+ * with the render API's `setState`/`reset`. An eager loader (its `request`
+ * returns a shape at mount) already carries `data` on first render; a lazy
+ * one (returns `null` until `state` supplies what it needs) is idle until
+ * a `setState` makes its `request` return a shape.
+ */
+// deno-lint-ignore no-explicit-any
+type LoaderHandle<L extends Loader<any, any, any, any>> = UseQueryResult<LoaderData<L>, Error>;
+
+/**
+ * An action handle: tanstack's `UseMutationResult` so authors get
+ * `mutate`, `mutateAsync`, `isPending`, `reset`, etc. The output type
+ * narrows to `InferOutput<outputSchema>` when declared and falls back to
+ * `unknown` when omitted.
+ */
+type ActionOutput<A> =
+  // deno-lint-ignore no-explicit-any
+  A extends Action<ZodType, any, infer Out>
+    ? Out extends ZodType
+      ? InferOutput<Out>
+      : unknown
+    : unknown;
+
+// deno-lint-ignore no-explicit-any
+type ActionHandle<A extends Action<any, any, any>> = UseMutationResult<
+  ActionOutput<A>,
+  Error,
+  InferInput<A["inputSchema"]>
+>;
+
+/**
+ * Read endpoint. Home forwards calls to a worker, which finds the named
+ * container by labels and dials it on the per-app `realm_<appId>` bridge.
+ *
+ * `service`/`port` name *which* container — the grant boundary, so they're
+ * static and Home-controlled. `request(state, config)` builds the actual
+ * call (`{ method, path, query?, body? }`) from the widget's state and
+ * config, or returns `null` for "not ready" (idle/lazy). Headers can be
+ * literal strings or refs (e.g. `r.stableSecret(...)`); Home resolves refs
+ * before the call so the iframe never sees the value.
+ *
+ * Generic on the widget's state/config types (so `request`'s params infer
+ * from the surface's `stateSchema`/`configSchema` when authored inline)
+ * and on the output Zod type (so `merge`'s `results` infers as
+ * `WorkerResult<InferOutput<TOut>>[]`). Wrap literals with `loader({...})`
+ * to pin them.
+ */
+export interface Loader<
+  TState = unknown,
+  TConfig = unknown,
+  TOut extends ZodType = ZodType,
+  TMerged = InferOutput<TOut>,
+> {
+  /** Service name within this app (the grant boundary). */
+  service: string;
+  /** Container port to forward to. */
+  port: number;
+  /** Static or ref headers (e.g. `r.stableSecret(...)`); Home resolves refs. */
+  headers?: Record<string, string | Ref<string>>;
+  outputSchema: TOut;
+  /**
+   * Build the call from the widget's state + config, or return `null`
+   * when the state isn't ready (→ idle/lazy). Runs in the iframe per
+   * state change; also run once at eval against the state/config defaults
+   * so Home can prefill the eager case.
+   */
+  request: (state: TState, config: TConfig) => RequestShape | null;
+  /**
+   * Fan out across every worker the app is deployed on, then reduce the
+   * per-worker responses to the shape this loader hands the render fn as
+   * `data`. That merged shape need not match `outputSchema`: `outputSchema`
+   * is the per-worker wire contract (validated once per response, never
+   * against the merged result), while `merge`'s return is the view — e.g.
+   * folding N single-host responses into one `{ hosts: [...] }` list, or
+   * tagging each with the worker that answered. Defaults to
+   * `InferOutput<outputSchema>` for the common flatten-in-place case.
+   */
+  merge?: (results: WorkerResult<InferOutput<TOut>>[]) => TMerged;
+  /**
+   * Poll interval for this loader (ms), or a function of the query that
+   * returns one (return `false` to stop). Lives on the definition — not
+   * the call site — so it rides the esbuild bundle; a function interval
+   * can't survive the JSON manifest / QuickJS boundary. Omitted = no
+   * polling.
+   */
+  refetchInterval?: LoaderQueryOptions["refetchInterval"];
+}
+
+/**
+ * Mutation endpoint. Like `Loader` but the caller passes an explicit
+ * `input` at call time (`mutateAsync(input)`) rather than reading the
+ * widget's state, and the runtime hook is a tanstack-query mutation
+ * (`useMutation`) — authors get `mutate` / `mutateAsync` / `isPending`
+ * instead of `data` / `refetch`. `request(input, config)` builds the call
+ * from that argument and the surface config.
+ *
+ * On a system app the action fans out to every reachable worker
+ * and `mutateAsync` resolves with `{ results, failures }`, where `results`
+ * is a {@link WorkerResult} per worker that answered. Actions don't have a
+ * `merge` knob — the caller decides what to do with the per-worker array
+ * (usually nothing; just invalidate a loader). On a single app the action
+ * targets one worker and resolves with the upstream body directly.
+ *
+ * Authors invalidate loader caches after a mutation either via the loader
+ * handle's `.refetch()` or
+ * `queryClient.invalidateQueries({ queryKey: ["loader", "name"] })`.
+ */
+export interface Action<
+  TIn extends ZodType = ZodType,
+  TConfig = unknown,
+  TOut extends ZodType = ZodType,
+> {
+  inputSchema: TIn;
+  /**
+   * Optional. If omitted, Home returns the upstream body unparsed
+   * (`unknown`). Tanstack's `mutateAsync` still resolves with that
+   * value; just no schema-checked narrowing.
+   */
+  outputSchema?: TOut;
+  /** Service name within this app (the grant boundary). */
+  service: string;
+  /** Container port to forward to. */
+  port: number;
+  /** Static or ref headers (e.g. `r.stableSecret(...)`); Home resolves refs. */
+  headers?: Record<string, string | Ref<string>>;
+  /** Build the call from the mutate argument + surface config. */
+  request: (input: InferInput<TIn>, config: TConfig) => ActionRequestShape;
+}
+
+/**
+ * A page mounts as a sidebar entry in Home. Author owns the whole
+ * route's content area; no tile chrome, no size hints.
+ */
+export interface Page<
+  TState extends ZodType = ZodType,
+  TConfig extends SurfaceConfigSchema = SurfaceConfigSchema,
+  // deno-lint-ignore no-explicit-any
+  TLoaders extends Record<string, Loader<any, any, any>> = Record<string, Loader>,
+  // deno-lint-ignore no-explicit-any
+  TActions extends Record<string, Action<any, any, any>> = Record<string, Action>,
+> {
+  title: string;
+  /**
+   * Icon name from `icons.tsx`, e.g. `"ListChecksIcon"` or `"CubeIcon"`.
+   * Drives the sidebar entry / tile glyph at first install; Home
+   * operator can override it later. Required so every surface is a
+   * deliberate choice — pick `"FadersIcon"` if you genuinely want the
+   * generic look.
+   */
+  icon: IconName;
+  /**
+   * The surface's live UI state, driven from inside the widget via
+   * `setState`. A loader's `request` reads it. Omit for a surface with no
+   * interactive state (every loader eager). Its `{}`-parse seeds the
+   * initial state.
+   */
+  stateSchema?: TState;
+  loaders?: TLoaders;
+  actions?: TActions;
+  // deno-lint-ignore no-explicit-any
+  render: (
+    api: RenderApi<TLoaders, TActions, InferOutput<TState>, InferConfigSchema<TConfig>>,
+  ) => any;
+}
+
+/**
+ * A widget mounts as a tile on the Home homepage grid. Adds size hints
+ * to the page shape: `cols`/`rows` count 8rem grid cells, both default
+ * to 2 (16rem square) when omitted.
+ *
+ * Below the `sm` breakpoint (640px) the grid collapses to two
+ * full-width cells: `cols` clamps to 2 and `rows` grows proportionally
+ * (`ceil(cols * rows / min(cols, 2))`) so the widget keeps its area
+ * for content to reflow into. A `rows === 1` widget renders without
+ * the title-bar chrome on every viewport — the author owns labeling
+ * inside the iframe — and that intent carries across the mobile
+ * collapse even when effective rows grow.
+ *
+ * `cols` and `rows` must be integers ≥ 1.
+ */
+export interface Widget<
+  TState extends ZodType = ZodType,
+  TConfig extends SurfaceConfigSchema = SurfaceConfigSchema,
+  // deno-lint-ignore no-explicit-any
+  TLoaders extends Record<string, Loader<any, any, any>> = Record<string, Loader>,
+  // deno-lint-ignore no-explicit-any
+  TActions extends Record<string, Action<any, any, any>> = Record<string, Action>,
+> extends Page<TState, TConfig, TLoaders, TActions> {
+  /**
+   * The widget's settings, set outside the widget on the tile's config screen
+   * and persisted per-placement by Home. A flat record of `r.input.*` leaves
+   * (text / number / boolean / enum — no secrets, no permissions); the config
+   * form renders from it and a loader's `request(state, config)` reads the
+   * resolved values. Widgets only — pages aren't configurable.
+   */
+  configSchema?: TConfig;
+  cols?: number;
+  rows?: number;
+}
+
+/** The `ui:` block on `createApp`. */
+export interface UiConfig {
+  // deno-lint-ignore no-explicit-any
+  pages?: Record<string, Page<any, any, any, any>>;
+  // deno-lint-ignore no-explicit-any
+  widgets?: Record<string, Widget<any, any, any, any>>;
+}
+
+/**
+ * Capture per-call generics so `request`'s `(state, config)` params infer
+ * from the surface's `stateSchema`/`configSchema` (when authored inline)
+ * and `merge`'s `results` infers as `z.infer<outputSchema>[]`.
+ *
+ * Identity at runtime — TS-only ergonomics. Always wrap loader literals
+ * with this.
+ */
+export function loader<
+  TOut extends ZodType,
+  TMerged = InferOutput<TOut>,
+  TState = unknown,
+  TConfig = unknown,
+>(def: Loader<TState, TConfig, TOut, TMerged>): Loader<TState, TConfig, TOut, TMerged> {
+  return def;
+}
+
+/**
+ * Action counterpart to `loader()`. Identity at runtime; the wrapper lets
+ * TS pin the per-call generics on `inputSchema` / `outputSchema` so
+ * `actions.{name}.mutateAsync(input)` is typed against the exact shapes
+ * the author declared.
+ */
+export function action<TIn extends ZodType, TConfig = unknown, TOut extends ZodType = ZodType>(
+  def: Action<TIn, TConfig, TOut>,
+): Action<TIn, TConfig, TOut> {
+  return def;
+}
+
+/**
+ * Capture a page's `stateSchema` / `loaders` / `actions` so the `render`
+ * function's handles + `state` are typed per-surface. Without this wrapper the
+ * outer `Record<string, Page>` constraint on `UiConfig.pages` widens them,
+ * losing inference. Pages take no config (only widgets are configurable), so
+ * the config type is pinned empty and a `configSchema` here is a type error.
+ */
+export function page<
+  TState extends ZodType,
+  // deno-lint-ignore no-explicit-any
+  TLoaders extends Record<string, Loader<any, any, any>>,
+  // deno-lint-ignore no-explicit-any
+  TActions extends Record<string, Action<any, any, any>>,
+>(
+  def: Page<TState, Record<string, never>, TLoaders, TActions>,
+): Page<TState, Record<string, never>, TLoaders, TActions> {
+  return def;
+}
+
+/** Widget counterpart to `page()` — same role, accepts `cols`/`rows`. */
+export function widget<
+  TState extends ZodType,
+  TConfig extends SurfaceConfigSchema,
+  // deno-lint-ignore no-explicit-any
+  TLoaders extends Record<string, Loader<any, any, any>>,
+  // deno-lint-ignore no-explicit-any
+  TActions extends Record<string, Action<any, any, any>>,
+>(def: Widget<TState, TConfig, TLoaders, TActions>): Widget<TState, TConfig, TLoaders, TActions> {
+  return def;
+}
+
+// Wire-side manifest types (`SurfaceManifest`, `WidgetManifest`,
+// `UiManifest`, `LoaderManifest`, `ManifestHeader`) live in
+// `resolve.ts` where the zod schemas they're inferred from are
+// declared. Internal SDK code imports them from `./resolve.ts`;
+// external consumers go through the `@yourrealm/sdk/compile` barrel.

package/src/valkey.ts

@@ -0,0 +1,43 @@
+import type { Ref } from "./ref.ts";
+import { interpolate as i } from "./ref.ts";
+import { Service } from "./service.ts";
+
+interface ValkeyOptions {
+  memory?: string;
+}
+
+export class Valkey extends Service {
+  readonly image: string;
+  readonly port = 6379;
+
+  constructor(_options?: ValkeyOptions) {
+    super();
+    this.image = "valkey/valkey:8";
+  }
+
+  get password(): Ref<string> {
+    return this.derived("valkey-password");
+  }
+
+  get url(): Ref<string> {
+    return i`redis://default:${this.password}@${this.host}:${this.port}/0`;
+  }
+
+  getServiceDefinition() {
+    return {
+      image: this.image,
+      volumes: [
+        {
+          hostPath: i`./data/${this.host}`,
+          containerPath: "/var/lib/valkey/data",
+          backup: { kind: "valkey-save" as const, url: this.url },
+        },
+      ],
+      command: ["--requirepass", this.password],
+      env: { REDISCLI_AUTH: this.password },
+      healthcheck: {
+        test: ["CMD", "valkey-cli", "PING"],
+      },
+    };
+  }
+}

package/src/worker/extract-tar.ts

@@ -0,0 +1,125 @@
+import { dirname, resolve } from "@std/path";
+import { log } from "@local/logger";
+import { UntarStream } from "@std/tar";
+
+// state.json carries every resolved env / API key / derived password
+// for every app on this worker. It's captured in memory and parsed
+// in-process, never landing on disk. Bind-mount artifacts (under
+// files/) do hit disk, but with 0o600 perms.
+const IN_MEMORY_TAR_ENTRY = "state.json";
+
+// Entries at or under this land in one write(2); larger ones stream, and a
+// stream can be observed mid-write. In practice only artifacts get this big,
+// and artifacts are content-addressed — a rewrite puts back byte-identical
+// bytes, so there's nothing to observe. Nothing caps an inline file's size
+// though, so a big enough one gives up the single-syscall guarantee.
+const BUFFERED_WRITE_MAX_BYTES = 8 * 1024 * 1024;
+
+/** `write(2)` can come up short on a large buffer; loop until it all lands. */
+async function writeAll(file: Deno.FsFile, buf: Uint8Array<ArrayBufferLike>): Promise<number> {
+  let offset = 0;
+  while (offset < buf.length) offset += await file.write(buf.subarray(offset));
+  return buf.length;
+}
+
+interface ExtractResult {
+  /** Plaintext state.json content captured in memory, never written to disk. */
+  stateJsonString: string | null;
+}
+
+/**
+ * Extract a gzipped tar stream under destDir. Rejects entries whose
+ * resolved path escapes destDir (path traversal via `..` or
+ * absolute paths). Only regular files and directories are written;
+ * symlinks, hardlinks, devices, FIFOs, etc. are skipped — Home
+ * emits only typeflags "0" (file) and "5" (directory), so anything
+ * else on the wire is either malformed or adversarial.
+ *
+ * The entry whose resolved path equals `destDir/state.json` is
+ * captured into the returned `ExtractResult` and never written to
+ * disk — state.json holds resolved secrets and is parsed in memory.
+ * The compare runs on the *resolved* dest so path variants like
+ * `./././state.json` can't bypass it. Everything else streams to
+ * disk with 0o600 (files) / 0o700 (dirs); we chmod after every
+ * write so a pre-existing inode with looser permissions gets
+ * retightened (Deno's `mode` arg only applies on creation).
+ *
+ * Files are rewritten **in place, on the existing inode**. Inline
+ * files are keyed by identity (sha of `appId:serviceKey:fileKey`),
+ * not content, so a content change reuses the same path — and that
+ * path is a single-file bind mount into containers that are already
+ * running. Docker attaches the inode, so the usual write-to-temp-
+ * then-rename recipe would rebind only the name and freeze every
+ * running container at the bytes it booted with, silently and
+ * forever. So: no `O_TRUNC` (the file is never observably empty),
+ * one `write(2)` for anything that fits in memory (a racing reader's
+ * window is a syscall, not the whole network transfer), and
+ * `truncate` last (a shrink reads as new-prefix + old-tail, which
+ * won't parse, rather than a valid bare prefix).
+ */
+export async function extractTarToWorkerDir(
+  tarGz: ReadableStream<Uint8Array<ArrayBufferLike>>,
+  destDir: string,
+): Promise<ExtractResult> {
+  const root = resolve(destDir);
+  const rootPrefix = root + "/";
+  const stateDest = resolve(root, IN_MEMORY_TAR_ENTRY);
+  let stateJsonString: string | null = null;
+
+  const untarred = (tarGz as ReadableStream<Uint8Array<ArrayBuffer>>)
+    .pipeThrough(new DecompressionStream("gzip"))
+    .pipeThrough(new UntarStream());
+
+  for await (const entry of untarred) {
+    const dest = resolve(root, entry.path);
+    if (dest !== root && !dest.startsWith(rootPrefix)) {
+      await entry.readable?.cancel();
+      throw new Error(`tar entry escapes destination: ${entry.path}`);
+    }
+
+    const typeflag = entry.header.typeflag;
+    if (typeflag === "5") {
+      await Deno.mkdir(dest, { recursive: true, mode: 0o700 });
+      await Deno.chmod(dest, 0o700);
+    } else if (typeflag === "0" || typeflag === "") {
+      // The size field is `parseInt(octal)`, so a corrupt header yields NaN (or
+      // a negative), and UntarStream then hands back an empty body — which is
+      // indistinguishable from a legitimately empty entry right up until it
+      // truncates a live bind-mounted file to zero. Reject instead of writing.
+      const size = entry.header.size;
+      if (!Number.isFinite(size) || size < 0) {
+        await entry.readable?.cancel();
+        throw new Error(`tar entry has an invalid size header: ${entry.path}`);
+      }
+
+      if (dest === stateDest) {
+        const buf = new Uint8Array(await new Response(entry.readable!).arrayBuffer());
+        stateJsonString = new TextDecoder().decode(buf);
+        continue;
+      }
+      const parent = dirname(dest);
+      await Deno.mkdir(parent, { recursive: true, mode: 0o700 });
+      await Deno.chmod(parent, 0o700);
+
+      const buffered =
+        size <= BUFFERED_WRITE_MAX_BYTES
+          ? new Uint8Array(await new Response(entry.readable!).arrayBuffer())
+          : null;
+      const file = await Deno.open(dest, { write: true, create: true, mode: 0o600 });
+      try {
+        let written = 0;
+        if (buffered !== null) written = await writeAll(file, buffered);
+        else for await (const chunk of entry.readable!) written += await writeAll(file, chunk);
+        await file.truncate(written);
+      } finally {
+        file.close();
+      }
+      await Deno.chmod(dest, 0o600);
+    } else {
+      log.warn(`Skipping tar entry with unsupported typeflag "${typeflag}": ${entry.path}`);
+      await entry.readable?.cancel();
+    }
+  }
+
+  return { stateJsonString };
+}