@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/product-stream-miss.ts

@@ -0,0 +1,12 @@
+// The streaming validator's refusal when a check asks for bytes the stream
+// did not hold (API-CLOUDFLARE AC6a2): a host never takes a guess for the
+// check, and the corpus and pin tests prove no check does.
+
+class StreamMissError extends Error {
+  public constructor(message: string) {
+    super(message)
+    this.name = 'StreamMissError'
+  }
+}
+
+export { StreamMissError }

package/src/format/product-stream-node.ts

@@ -0,0 +1,47 @@
+// `validateShardfileStream`'s ports from `node:crypto` and `node:zlib`, which
+// a Worker has under `nodejs_compat` (API-CLOUDFLARE AC6a). A host adapter,
+// not the portable library: tsconfig.lib.json leaves it out.
+
+// oxlint-disable-next-line import/no-nodejs-modules -- a Node and Workers host adapter
+import { createHash } from 'node:crypto'
+// oxlint-disable-next-line import/no-nodejs-modules -- a Node and Workers host adapter
+import { Readable, pipeline } from 'node:stream'
+// oxlint-disable-next-line import/no-nodejs-modules -- a Node and Workers host adapter
+import { createBrotliDecompress } from 'node:zlib'
+
+import type { StreamHasher } from './product-stream-tar.ts'
+import type { StreamValidationPorts } from './product-stream.ts'
+
+function sha256(bytes: Readonly<Uint8Array>): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+function hasher(): StreamHasher {
+  const hash = createHash('sha256')
+  return {
+    update: (bytes: Readonly<Uint8Array>): void => {
+      hash.update(bytes)
+    },
+    digest: (): string => hash.digest('hex'),
+  }
+}
+
+/** Brotli-decode a stored object's chunks. A decoding error ends the stream with it. */
+function brotliDecode(
+  stored: AsyncIterable<Uint8Array>,
+): AsyncIterable<Uint8Array> {
+  return pipeline(Readable.from(stored), createBrotliDecompress(), (): void => {
+    // The reader sees the error: the decoder's stream is destroyed with it.
+  })
+}
+
+/** The ports for a `.tar.br` stored object (`brotli: true`) or a plain tarball. */
+function nodeStreamPorts(
+  options: Readonly<{ brotli: boolean }>,
+): StreamValidationPorts {
+  return options.brotli
+    ? { hash: sha256, hasher, decode: brotliDecode }
+    : { hash: sha256, hasher }
+}
+
+export { nodeStreamPorts }

package/src/format/product-stream-packs.ts

@@ -0,0 +1,242 @@
+// oxlint-disable eslint/max-params, eslint/max-statements, eslint/max-lines-per-function, typescript/prefer-readonly-parameter-types -- the old validator's steps in its order, over reads that share state; the state is only read but for the held maps
+// `checkPacks` for the streaming validator (API-CLOUDFLARE AC6a2). A carried
+// pack's members are checked against its slices as it streams past. A pack
+// the tarball leaves out is rebuilt by hashing its members in entry order
+// (`parseOutputIndex` holds them contiguous, at their listed sizes, from 0 to
+// the pack's size). The tarball is sorted by path, not by pack order, so a
+// member that streams early waits, held, until the members before it pass.
+// The packs are split into groups whose held bytes stay under a cap, and
+// each group takes its own read of the stored object.
+
+import type { OutputIndex } from './outputIndex.ts'
+import type { StreamHasher } from './product-stream-tar.ts'
+
+type Pack = NonNullable<OutputIndex['packs']>[number]
+
+/** The most member bytes one read holds for its left-out packs. */
+const PACK_HOLD_CAP = 16_000_000
+const NONE = 0
+const NEXT = 1
+
+/** A left-out pack being rebuilt: the next entry to hash, and the ones that came early. */
+interface PackRun {
+  readonly pack: Pack
+  readonly paths: readonly string[]
+  readonly hasher: StreamHasher
+  readonly early: Map<number, Readonly<Uint8Array>>
+  cursor: number
+}
+
+/** What one read found for its packs: by pack path, the refusal or undefined. */
+type PackVerdicts = Map<string, string | undefined>
+
+/** Each pack member's listed path: `packFromMembers`' lookup, the last listed row of a hash winning. */
+function memberPaths(
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+): ReadonlyMap<string, string> {
+  return new Map(
+    [...index.sections, ...index.schemas, ...index.files].map(
+      (row: Readonly<{ hash: string; path: string }>): [string, string] => [
+        row.hash,
+        row.path,
+      ],
+    ),
+  )
+}
+
+/** A pack's entry paths, in entry order. */
+function entryPaths(
+  pack: Readonly<Pack>,
+  paths: ReadonlyMap<string, string>,
+): string[] {
+  return pack.entries.map(
+    (entry: Readonly<{ hash: string }>): string => paths.get(entry.hash) ?? '',
+  )
+}
+
+/** A left-out pack in `heldPeak`: sizes only. */
+interface SizedRun {
+  readonly paths: readonly string[]
+  readonly early: Set<number>
+  cursor: number
+}
+
+/** Which entries of which pack wait on each path. */
+function waitsByPath<Run extends Readonly<{ paths: readonly string[] }>>(
+  runs: readonly Run[],
+): Map<string, { run: Run; at: number }[]> {
+  const waits = new Map<string, { run: Run; at: number }[]>()
+  for (const run of runs) {
+    for (const [at, path] of run.paths.entries()) {
+      waits.set(path, [...(waits.get(path) ?? []), { run, at }])
+    }
+  }
+  return waits
+}
+
+/** The most bytes a group of left-out packs holds in one read, members arriving in `order`: `packPass`, by size. */
+function heldPeak(
+  group: readonly (readonly string[])[],
+  order: readonly string[],
+  sizes: ReadonlyMap<string, number>,
+): number {
+  const runs = group.map((paths: readonly string[]): SizedRun => ({
+    paths,
+    cursor: NONE,
+    early: new Set<number>(),
+  }))
+  const waits = waitsByPath(runs)
+  let held = NONE
+  let peak = NONE
+  for (const path of order) {
+    for (const { run, at } of waits.get(path) ?? []) {
+      run.early.add(at)
+      held += sizes.get(path) ?? NONE
+      peak = Math.max(peak, held)
+      while (run.early.delete(run.cursor)) {
+        held -= sizes.get(run.paths[run.cursor] ?? '') ?? NONE
+        run.cursor += NEXT
+      }
+    }
+  }
+  return peak
+}
+
+/** The left-out packs in read groups, each under `PACK_HOLD_CAP` held (a pack alone over it still gets a group). */
+function packGroups(
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+  present: ReadonlySet<string>,
+  order: readonly string[],
+  sizes: ReadonlyMap<string, number>,
+): Pack[][] {
+  const paths = memberPaths(index)
+  const groups: Pack[][] = []
+  let group: Pack[] = []
+  for (const pack of index.packs ?? []) {
+    if (!present.has(pack.path)) {
+      const next = [...group, pack]
+      const peak = heldPeak(
+        next.map((row: Readonly<Pack>): string[] => entryPaths(row, paths)),
+        order,
+        sizes,
+      )
+      if (peak > PACK_HOLD_CAP && group.length > NONE) {
+        groups.push(group)
+        group = [pack]
+      } else {
+        group = next
+      }
+      if (
+        group.length === NEXT &&
+        heldPeak([entryPaths(pack, paths)], order, sizes) > PACK_HOLD_CAP
+      ) {
+        throw new Error(`stream: a pack over the streaming cap: ${pack.path}`)
+      }
+    }
+  }
+  return group.length > NONE ? [...groups, group] : groups
+}
+
+/** One read's pack checks: carried packs against their slices, a group of left-out packs rebuilt. */
+interface PackPass {
+  /** Paths whose bytes this read needs. */
+  readonly wants: ReadonlySet<string>
+  /** One member's bytes, in tarball order. */
+  readonly member: (path: string, bytes: Readonly<Uint8Array>) => void
+  /** The bytes held now for left-out packs. */
+  readonly held: () => number
+  /** Each pack's refusal, or undefined, once the read ends. */
+  readonly finish: () => PackVerdicts
+}
+
+function packPass(
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+  packs: Readonly<{ carried: readonly Pack[]; group: readonly Pack[] }>,
+  ports: Readonly<{
+    hash: (bytes: Readonly<Uint8Array>) => string
+    hasher: () => StreamHasher
+  }>,
+): PackPass {
+  const paths = memberPaths(index)
+  const verdicts: PackVerdicts = new Map()
+  const { carried, group } = packs
+  const carriedByPath = new Map(
+    carried.map((pack: Readonly<Pack>): [string, Pack] => [pack.path, pack]),
+  )
+  const runs: PackRun[] = group.map((pack: Readonly<Pack>): PackRun => ({
+    pack,
+    paths: entryPaths(pack, paths),
+    hasher: ports.hasher(),
+    early: new Map(),
+    cursor: NONE,
+  }))
+  const waits = waitsByPath(runs)
+  let held = NONE
+  const advance = (run: PackRun): void => {
+    for (;;) {
+      const bytes = run.early.get(run.cursor)
+      if (bytes === undefined) {
+        return
+      }
+      run.early.delete(run.cursor)
+      held -= bytes.length
+      run.hasher.update(bytes)
+      run.cursor += NEXT
+    }
+  }
+  const member = (path: string, bytes: Readonly<Uint8Array>): void => {
+    const pack = carriedByPath.get(path)
+    if (pack !== undefined) {
+      const differs = pack.entries.some(
+        (
+          entry: Readonly<{ hash: string; offset: number; bytes: number }>,
+        ): boolean =>
+          ports.hash(
+            bytes.subarray(entry.offset, entry.offset + entry.bytes),
+          ) !== entry.hash,
+      )
+      verdicts.set(
+        pack.path,
+        differs ? `Pack member differs: ${pack.path}` : undefined,
+      )
+    }
+    for (const { run, at } of waits.get(path) ?? []) {
+      run.early.set(at, bytes)
+      held += bytes.length
+      advance(run)
+    }
+  }
+  const finish = (): PackVerdicts => {
+    for (const run of runs) {
+      if (run.cursor < run.paths.length) {
+        throw new Error(`missing file: ${run.paths[run.cursor] ?? ''}`)
+      }
+      verdicts.set(
+        run.pack.path,
+        run.hasher.digest() === run.pack.hash
+          ? undefined
+          : `Pack differs from its members: ${run.pack.path}`,
+      )
+    }
+    return verdicts
+  }
+  return {
+    wants: new Set([...carriedByPath.keys(), ...waits.keys()]),
+    member,
+    held: (): number => held,
+    finish,
+  }
+}
+
+export type { PackPass, PackVerdicts }
+export {
+  PACK_HOLD_CAP,
+  heldPeak,
+  memberPaths,
+  entryPaths,
+  packGroups,
+  packPass,
+}

package/src/format/product-stream-rows.ts

@@ -0,0 +1,202 @@
+// `validateShardfileProduct`'s inventory steps, replayed over what one
+// streaming pass kept (API-CLOUDFLARE AC6a): each listed file's hash and
+// size, the blobs' facts, server files, KTX2 device costs, the cook and its
+// mounts, and no unlisted file. The order and the messages are the old ones.
+// The index and script rows are valibot's output types, which the replay only
+// reads; their parameters say so in a disable comment rather than a deep type.
+
+import { cookMountPath, readCookData } from './cook-data.ts'
+import { requireCookPreparation } from './cook-preparation.ts'
+import { validatePlatformFile } from './platformFileFamilies.ts'
+import { mountSharesBlob } from './product-reads.ts'
+import { inspectFacts, ktx2Text } from './product-stream-facts.ts'
+import { outputBlobKind, readCanonicalJson } from './productValidation.ts'
+import { decisionModuleContracts } from './scriptContract.ts'
+import { validationSourceBytes } from './validationReceipt.ts'
+
+import type { OutputIndex } from './outputIndex.ts'
+import type { FactsMember } from './product-stream-facts.ts'
+import type { StreamMember } from './product-stream-tar.ts'
+import type { ScriptAdmissionRows } from './scriptContract.ts'
+
+/** One tar member after the walk. */
+type KeptMember = FactsMember & StreamMember
+
+interface Listed {
+  readonly path: string
+  readonly hash: string
+  readonly bytes: number
+}
+
+/** The members the walk kept, and the paths the replay has listed so far. */
+interface Replay {
+  readonly members: ReadonlyMap<string, KeptMember>
+  readonly listed: Set<string>
+  readonly hash: (bytes: Readonly<Uint8Array>) => string
+}
+
+const NONE = 0
+
+/** A listed file: present, no larger than declared, and of its exact hash and size. */
+function readListed(
+  replay: Readonly<Replay>,
+  entry: Readonly<Listed>,
+): KeptMember {
+  replay.listed.add(entry.path)
+  const member = replay.members.get(entry.path)
+  if (member === undefined) {
+    throw new Error(`missing file: ${entry.path}`)
+  }
+  if (member.size > entry.bytes) {
+    throw new Error(`larger than its declared size: ${entry.path}`)
+  }
+  if (member.size !== entry.bytes || member.sha !== entry.hash) {
+    throw new Error(`Output hash or size mismatch: ${entry.path}`)
+  }
+  return member
+}
+
+/** A listed file's kept bytes. */
+function listedBytes(
+  replay: Readonly<Replay>,
+  entry: Readonly<Listed>,
+): Uint8Array {
+  const { bytes } = readListed(replay, entry)
+  if (bytes === undefined) {
+    throw new Error(`stream: ${entry.path} was not kept`)
+  }
+  return bytes
+}
+
+/** Every listed blob through `inspectBlob`'s checks; the members by asset key, for `ktx2Costs`. */
+function replayFiles(
+  replay: Readonly<Replay>,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- format's row type, only read
+  scripts: ScriptAdmissionRows,
+): Map<string, KeptMember> {
+  const contracts = decisionModuleContracts(scripts, index.files)
+  const assets = new Map<string, KeptMember>()
+  for (const entry of index.files) {
+    const member = readListed(replay, {
+      path: entry.path,
+      hash: entry.hash,
+      bytes: entry.compressed,
+    })
+    inspectFacts(
+      entry,
+      member,
+      entry.kind === 'wasm'
+        ? (contracts.get(entry.hash) ?? { abi: 0 })
+        : undefined,
+    )
+    assets.set(
+      `${entry.commons === true ? 'commons:' : ''}${entry.hash}`,
+      member,
+    )
+    if (index.requires.commons.includes(entry.hash)) {
+      assets.set(`commons:${entry.hash}`, member)
+    }
+  }
+  return assets
+}
+
+/** J91's server files, and the declared KTX2 device costs against the verified bytes. */
+function replayServerAndKtx2(
+  replay: Readonly<Replay>,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+  assets: ReadonlyMap<string, KeptMember>,
+): void {
+  for (const entry of index.admission.server ?? []) {
+    const bytes = listedBytes(replay, entry)
+    if (entry.kind === 'json') {
+      if (
+        validatePlatformFile(
+          entry.name,
+          entry.schema,
+          readCanonicalJson(bytes),
+        ) === undefined
+      ) {
+        throw new Error(`Unregistered named JSON: ${entry.name}`)
+      }
+    } else if (outputBlobKind('binary', bytes) !== entry.kind) {
+      throw new Error('Output blob bytes differ from their declared kind')
+    }
+  }
+  for (const [hash, cost] of Object.entries(index.ktx2Costs ?? {})) {
+    const actual = ktx2Text(assets.get(hash))
+    if (
+      actual === undefined ||
+      new TextDecoder().decode(validationSourceBytes(cost)) !== actual
+    ) {
+      throw new Error('KTX2 device costs differ from verified bytes')
+    }
+  }
+}
+
+/** C0 (J137): the cook file, and each mount's hash and size. */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function replayCook(replay: Readonly<Replay>, index: OutputIndex): void {
+  const cook =
+    index.cook === undefined
+      ? undefined
+      : readCookData(readCanonicalJson(listedBytes(replay, index.cook)))
+  requireCookPreparation(index, cook, replay.hash)
+  for (const mount of cook?.mounts ?? []) {
+    if (!mountSharesBlob(mount, index.files)) {
+      if (mount.path !== cookMountPath(mount.url)) {
+        throw new Error(`Mount path differs from its URL: ${mount.url}`)
+      }
+      readListed(replay, mount)
+    }
+  }
+}
+
+/** No copied runtime files (the Worker has no import checker) and no file the index does not list. */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function replayInventory(replay: Readonly<Replay>, index: OutputIndex): void {
+  if ((index.runtime?.files ?? []).length > NONE) {
+    throw new Error('Copied runtime files need a runtime import checker')
+  }
+  for (const path of replay.members.keys()) {
+    if (!replay.listed.has(path)) {
+      throw new Error(`Unlisted output file: ${path}`)
+    }
+  }
+}
+
+/** The steps from the blobs to the KTX2 costs, before the packs. */
+function replayBeforePacks(
+  replay: Readonly<Replay>,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- format's row type, only read
+  scripts: ScriptAdmissionRows,
+): void {
+  replayServerAndKtx2(replay, index, replayFiles(replay, index, scripts))
+}
+
+/** `checkPacks` in pack order, from what the later reads found; then the cook, its mounts and the inventory. */
+function replayPacksToInventory(
+  replay: Readonly<Replay>,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+  packs: ReadonlyMap<string, string | undefined>,
+): void {
+  for (const pack of index.packs ?? []) {
+    if (replay.members.has(pack.path)) {
+      readListed(replay, pack)
+    }
+    const refusal = packs.get(pack.path)
+    if (refusal !== undefined) {
+      throw new Error(refusal)
+    }
+  }
+  replayCook(replay, index)
+  replayInventory(replay, index)
+}
+
+export type { KeptMember, Replay }
+export { listedBytes, replayBeforePacks, replayPacksToInventory }

package/src/format/product-stream-tar.ts

@@ -0,0 +1,192 @@
+// The streaming half of `indexTar` (API-CLOUDFLARE AC6a): one pass over a
+// tarball's chunks with the same refusals, in bounded memory. Each regular
+// file is hashed as it streams; the caller says which files it wants whole.
+
+import { BLOCK, padded } from './tar-fields.ts'
+import { MAX_ENTRIES, claimFile, claimFolder, newClaims } from './tar-paths.ts'
+import { readTarHeader } from './tar.ts'
+
+import type { TarClaims } from './tar-paths.ts'
+
+const START = 0
+const NUL = 0
+const NEXT = 1
+const END_BLOCKS = 2
+const DIRECTORY_TYPE = '5'
+const EMPTY: Uint8Array = new Uint8Array(START)
+
+/** An incremental SHA-256 (`node:crypto`'s `createHash('sha256')`). */
+interface StreamHasher {
+  readonly update: (bytes: Readonly<Uint8Array>) => void
+  readonly digest: () => string
+}
+
+/** One regular file of the tarball: its size and hash, and its bytes when the caller asked for them. */
+interface StreamMember {
+  readonly size: number
+  readonly sha: string
+  readonly bytes: Uint8Array | undefined
+}
+
+/** What the walk asks of its caller. */
+interface WalkPorts {
+  readonly hasher: () => StreamHasher
+  /** Whether to hand this file over whole; refuse here (throw) a file too large to hold. */
+  readonly wants: (path: string, size: number) => boolean
+  /** Called once per regular file, in tarball order. */
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- a port's own type: the caller keeps the bytes
+  readonly member: (path: string, member: StreamMember) => void
+}
+
+/** Exact-length reads over a chunk stream. */
+interface ChunkReader {
+  /** Up to `length` bytes in pieces; fewer only at the end of the stream. */
+  readonly pieces: (length: number) => AsyncGenerator<Uint8Array>
+  /** `length` bytes joined, or fewer at the end of the stream. */
+  readonly read: (length: number) => Promise<Uint8Array>
+}
+
+function isZero(bytes: Readonly<Uint8Array>): boolean {
+  return bytes.every((byte: number): boolean => byte === NUL)
+}
+
+function chunkReader(source: AsyncIterable<Uint8Array>): ChunkReader {
+  const chunks = source[Symbol.asyncIterator]()
+  let head = EMPTY
+  async function fill(): Promise<boolean> {
+    while (head.length === START) {
+      // oxlint-disable-next-line eslint/no-await-in-loop -- a stream's chunks come one at a time
+      const next = await chunks.next()
+      if (next.done === true) {
+        return false
+      }
+      head = next.value
+    }
+    return true
+  }
+  async function* pieces(length: number): AsyncGenerator<Uint8Array> {
+    let left = length
+    // oxlint-disable-next-line eslint/no-await-in-loop -- a stream's chunks come one at a time
+    while (left > START && (await fill())) {
+      const take = Math.min(left, head.length)
+      yield head.subarray(START, take)
+      head = head.subarray(take)
+      left -= take
+    }
+  }
+  async function read(length: number): Promise<Uint8Array> {
+    const out = new Uint8Array(length)
+    let at = START
+    for await (const piece of pieces(length)) {
+      out.set(piece, at)
+      at += piece.length
+    }
+    return at === length ? out : out.subarray(START, at)
+  }
+  return { pieces, read }
+}
+
+/** The end-of-archive blocks: at least two, and nothing after them but zeros. */
+async function assertEnd(reader: ChunkReader): Promise<number> {
+  let rest = BLOCK
+  let zero = true
+  for await (const piece of reader.pieces(Number.MAX_SAFE_INTEGER)) {
+    rest += piece.length
+    zero &&= isZero(piece)
+  }
+  if (rest < END_BLOCKS * BLOCK || !zero) {
+    throw new Error('tar: bad end-of-archive blocks')
+  }
+  return rest
+}
+
+/** Copy `size` bytes through `hasher`, and into `bytes` when held; the count copied. */
+async function copyMember(
+  reader: ChunkReader,
+  size: number,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- `bytes` is the copy's destination
+  sink: Readonly<{ hasher: StreamHasher; bytes: Uint8Array | undefined }>,
+): Promise<number> {
+  let at = START
+  for await (const piece of reader.pieces(size)) {
+    sink.hasher.update(piece)
+    sink.bytes?.set(piece, at)
+    at += piece.length
+  }
+  return at
+}
+
+/** Stream one regular file through its hash, held whole when wanted; then its zero padding. */
+async function readMember(
+  reader: ChunkReader,
+  entry: Readonly<{ path: string; size: number }>,
+  ports: WalkPorts,
+): Promise<StreamMember> {
+  const hasher = ports.hasher()
+  const bytes = ports.wants(entry.path, entry.size)
+    ? new Uint8Array(entry.size)
+    : undefined
+  if ((await copyMember(reader, entry.size, { hasher, bytes })) < entry.size) {
+    throw new Error(`tar: truncated entry ${entry.path}`)
+  }
+  if (!isZero(await reader.read(padded(entry.size) - entry.size))) {
+    throw new Error(`tar: non-zero padding after ${entry.path}`)
+  }
+  return { size: entry.size, sha: hasher.digest(), bytes }
+}
+
+/** One header and its file; the bytes it took. */
+async function walkEntry(
+  reader: ChunkReader,
+  block: Readonly<Uint8Array>,
+  walk: Readonly<{ ports: WalkPorts; claims: TarClaims }>,
+): Promise<number> {
+  const entry = readTarHeader(block)
+  if (entry.type === DIRECTORY_TYPE) {
+    if (entry.size !== START) {
+      throw new Error(`tar: directory with a size ${entry.path}`)
+    }
+    if (entry.path !== '') {
+      claimFolder(walk.claims, entry.path)
+    }
+    return BLOCK
+  }
+  claimFile(walk.claims, entry.path)
+  walk.ports.member(entry.path, await readMember(reader, entry, walk.ports))
+  return BLOCK + padded(entry.size)
+}
+
+/** The next header block, refusing a tarball that ends without its end blocks. */
+async function nextBlock(reader: ChunkReader): Promise<Uint8Array> {
+  const block = await reader.read(BLOCK)
+  if (block.length < BLOCK) {
+    throw new Error('tar: truncated (no end-of-archive blocks)')
+  }
+  return block
+}
+
+/** Walk a tarball once, refusing what `indexTar` refuses; resolves with its byte length. */
+async function walkTar(
+  tar: AsyncIterable<Uint8Array>,
+  ports: WalkPorts,
+): Promise<number> {
+  const reader = chunkReader(tar)
+  const walk = { ports, claims: newClaims() }
+  let offset = START
+  for (let entries = START; ; entries += NEXT) {
+    // oxlint-disable-next-line eslint/no-await-in-loop -- a tarball's headers come in order
+    const block = await nextBlock(reader)
+    if (isZero(block)) {
+      // oxlint-disable-next-line eslint/no-await-in-loop -- the walk's last step, once
+      return offset + (await assertEnd(reader))
+    }
+    if (entries === MAX_ENTRIES) {
+      throw new Error(`tar: too many entries, over ${String(MAX_ENTRIES)}`)
+    }
+    // oxlint-disable-next-line eslint/no-await-in-loop -- a tarball's entries come in order
+    offset += await walkEntry(reader, block, walk)
+  }
+}
+
+export type { StreamHasher, StreamMember, WalkPorts }
+export { walkTar }