@stigmer/server 3.22.1 → 3.23.1-dev.20260923075205

package/src/domain/skill/controller.ts

@@ -13,10 +13,12 @@
  * optional deps; every absent-surface answer is a deliberate arm, not an
  * accident.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize/TransformResponse/
- * SendResponse steps (no multi-tenant auth or response transformation) and
- * serves artifact bytes itself instead of R2 pre-signed URLs — same
- * capability-URL trust model, same client semantics.
+ * Versus Stigmer Cloud, OSS excludes the TransformResponse/SendResponse
+ * steps (no response transformation). The transfer lane's capability
+ * URLs come from the blob driver through the staging port
+ * (transfer/staging.ts): the local driver's point at this server's own
+ * HTTP lane, a bucket driver's straight at the bucket — same
+ * capability-URL trust model, same client semantics, one code path.
  *
  * Proven by skill.conformance.test.ts (CONFORMANCE_TARGET=local) and
  * the co-located __tests__/ suites.
@@ -75,7 +77,6 @@ import {
   newAuthorizeResolvedTargetStep,
 } from "../../pipeline/steps/authorize-resolved-target.js";
 import { versionHistoryTarget } from "../../pipeline/steps/version-history.js";
-import { newAuthorizeVisibilityTransitionStep } from "../../pipeline/steps/visibility-gates.js";
 import {
   newCleanupIamPoliciesStep,
   newRecordVisibilityBeforeUpdateStep,
@@ -119,8 +120,11 @@ import {
 import { skillSearchExtractor } from "./search-extractor.js";
 import { ArtifactNotFoundError } from "./storage/artifact-storage.js";
 import type { SkillArtifactStorage } from "./storage/artifact-storage.js";
-import { downloadUrl, uploadUrl } from "./transfer/handler.js";
-import type { UploadSlots } from "./transfer/slots.js";
+import type {
+  ArchiveStaging,
+  DownloadCapability,
+  StagedUpload,
+} from "./transfer/staging.js";
 import {
   LIST_VERSIONS_RESPONSE_KEY,
   LIST_VERSIONS_SKILL_ID_KEY,
@@ -136,13 +140,6 @@ import {
  */
 const EXECUTION_ARTIFACT_DOWNLOAD_TIMEOUT_MS = 60_000;
 
-/** The transfer lane's controller-side pair (Go SetTransferLane). */
-export interface SkillTransferLaneDeps {
-  readonly slots: UploadSlots;
-  /** Externally-reachable base minted into upload and download URLs. */
-  readonly baseUrl: string;
-}
-
 export interface SkillControllerDeps {
   readonly store: Store;
   readonly logger: Logger;
@@ -158,11 +155,12 @@ export interface SkillControllerDeps {
    */
   readonly executionArtifactStorage?: ArtifactStorage;
   /**
-   * The HTTP transfer lane (Go SetTransferLane). Optional — absent,
-   * createArtifactUploadUrl and getArtifactDownloadUrl answer
-   * FailedPrecondition and push accepts inline bytes only.
+   * The transfer lane's staging port (Go SetTransferLane) over the skill
+   * blob driver. Optional — absent, createArtifactUploadUrl and
+   * getArtifactDownloadUrl answer FailedPrecondition and push accepts
+   * inline bytes only.
    */
-  readonly transferLane?: SkillTransferLaneDeps;
+  readonly staging?: ArchiveStaging;
 }
 
 /** Registers both skill services on the router (routes stage). */
@@ -222,7 +220,7 @@ async function push(
   await newPipeline<typeof PushSkillRequestSchema>("skill-push", deps.logger)
     .addStep(newAuthorizeStep(method, deps.authorizer))
     .addStep(newValidateProtoStep())
-    .addStep(newResolveArtifactSourceStep(deps.transferLane?.slots))
+    .addStep(newResolveArtifactSourceStep(deps.staging))
     .addStep(newBuildInitialSkillStep())
     .addStep(newExtractAndHashArtifactStep())
     .addStep(newResolveSlugForPushStep())
@@ -266,19 +264,20 @@ async function push(
 }
 
 /**
- * CreateArtifactUploadUrl — mints a short-lived, single-use HTTP upload
- * URL for an artifact exceeding the gRPC message cap (#675). The size gate
- * is the fail-loud half of the contract: an over-limit artifact is refused
- * with the actual limit in the message BEFORE any bytes move, instead of
- * surfacing as a transport error mid-upload.
+ * CreateArtifactUploadUrl — mints a short-lived, single-use upload URL for
+ * an artifact exceeding the gRPC message cap (#675): the blob driver's own
+ * PUT surface, through the staging port. The size gate is the fail-loud
+ * half of the contract: an over-limit artifact is refused with the actual
+ * limit in the message BEFORE any bytes move, instead of surfacing as a
+ * transport error mid-upload.
  */
 async function createArtifactUploadUrl(
   deps: SkillControllerDeps,
   req: CreateSkillArtifactUploadUrlRequest,
   ctx: HandlerContext,
 ): Promise<SkillArtifactUploadUrl> {
-  const lane = deps.transferLane;
-  if (lane === undefined) {
+  const staging = deps.staging;
+  if (staging === undefined) {
     throw failedPreconditionError(TRANSFER_LANE_NOT_CONFIGURED);
   }
 
@@ -307,15 +306,15 @@ async function createArtifactUploadUrl(
     );
   }
 
-  let minted: { ref: string; ttlMs: number };
+  let minted: StagedUpload;
   try {
-    minted = lane.slots.mint(Number(req.sizeBytes));
+    minted = await staging.mint(Number(req.sizeBytes));
   } catch (error) {
     throw internalError(error, "failed to mint upload reference");
   }
 
   return create(SkillArtifactUploadUrlSchema, {
-    url: uploadUrl(lane.baseUrl, minted.ref),
+    url: minted.url,
     artifactUploadRef: minted.ref,
     ttlSeconds: Math.trunc(minted.ttlMs / 1000),
   });
@@ -450,12 +449,6 @@ async function updateVisibility(
     )
     .addStep(newRecordVisibilityBeforeUpdateStep(UPDATE_VISIBILITY_SKILL_KEY))
     .addStep(newValidateVisibilityUpdateStep())
-    .addStep(
-      newAuthorizeVisibilityTransitionStep(
-        UPDATE_VISIBILITY_SKILL_KEY,
-        deps.authorizer,
-      ),
-    )
     .addStep(newSetVisibilityStep())
     .addStep(newPersistSkillForVisibilityUpdateStep(deps.store))
     .addStep(
@@ -738,17 +731,19 @@ async function getArtifact(
 
 /**
  * GetArtifactDownloadUrl — the transfer-lane twin of GetArtifact (#675):
- * stats (never loads) the artifact and mints its capability URL. The URL
- * does not expire on OSS (ttl_seconds = 0) — it embeds the same
- * content-hash capability a stored storage key would.
+ * stats (never loads) the artifact, then asks the staging port for its
+ * capability URL. ttl_seconds is the floor of the URL's validity: a bucket
+ * driver signs its GET for exactly that long, while the local lane's URL
+ * embeds the same content-hash capability the storage key does and never
+ * expires, so the floor holds there trivially.
  */
 async function getArtifactDownloadUrl(
   deps: SkillControllerDeps,
   req: GetArtifactRequest,
   ctx: HandlerContext,
 ): Promise<SkillArtifactDownloadUrl> {
-  const lane = deps.transferLane;
-  if (lane === undefined) {
+  const staging = deps.staging;
+  if (staging === undefined) {
     throw failedPreconditionError(TRANSFER_LANE_NOT_CONFIGURED);
   }
 
@@ -784,9 +779,16 @@ async function getArtifactDownloadUrl(
     throw internalError(error, "failed to stat skill artifact");
   }
 
+  let capability: DownloadCapability;
+  try {
+    capability = await staging.downloadUrl(req.artifactStorageKey);
+  } catch (error) {
+    throw internalError(error, "failed to mint skill artifact download URL");
+  }
+
   return create(SkillArtifactDownloadUrlSchema, {
-    url: downloadUrl(lane.baseUrl, req.artifactStorageKey),
-    ttlSeconds: 0,
+    url: capability.url,
+    ttlSeconds: Math.trunc(capability.ttlMs / 1000),
     sizeBytes: BigInt(size),
   });
 }

package/src/domain/skill/push.ts

@@ -81,7 +81,7 @@ import { skillSearchExtractor } from "./search-extractor.js";
 import { extractSkillMd } from "./storage/zip-gate.js";
 import type { ExtractSkillMdResult } from "./storage/zip-gate.js";
 import type { SkillArtifactStorage } from "./storage/artifact-storage.js";
-import type { UploadSlots } from "./transfer/slots.js";
+import type { ArchiveStaging } from "./transfer/staging.js";
 
 type PushDesc = typeof PushSkillRequestSchema;
 
@@ -99,9 +99,9 @@ export const SHOULD_CREATE_SKILL_KEY = "shouldCreateSkill";
  * pipeline/steps/resolve-artifact-source.ts for the semantics).
  */
 export function newResolveArtifactSourceStep(
-  slots: UploadSlots | undefined,
+  staging: ArchiveStaging | undefined,
 ): PipelineStep<PushDesc> {
-  return newSharedResolveArtifactSourceStep<PushDesc>(slots, {
+  return newSharedResolveArtifactSourceStep<PushDesc>(staging, {
     source: (req) => ({
       artifact: req.artifact,
       artifactUploadRef: req.artifactUploadRef,

package/src/domain/skill/transfer/handler.ts

@@ -1,24 +1,28 @@
 /**
  * Skill artifact transfer lane — ports pkg/domain/skill/transfer/handler.go:
  * the HTTP upload/download surface that carries skill artifact bytes
- * OUTSIDE the gRPC control plane (#675). The gRPC server caps messages at
- * 10MB while the skill layer permits 100MB artifacts, so inline bytes
- * physically cannot carry every valid skill.
+ * OUTSIDE the gRPC control plane (#675) when the blob driver is the local
+ * one. The gRPC server caps messages at 10MB while the skill layer permits
+ * 100MB artifacts, so inline bytes physically cannot carry every valid
+ * skill; a bucket driver signs URLs straight to its bucket and this lane
+ * carries nothing for it.
  *
  *   PUT {prefix}/uploads/{ref}  — stage artifact bytes (capability: ref)
  *   GET {prefix}/{storage_key}  — serve artifact bytes (capability: key)
  *
  * Neither route carries bearer auth by design: the URL is the credential,
- * mirroring cloud's pre-signed R2 URLs. Minting an upload URL requires the
+ * mirroring a bucket's pre-signed URLs. Minting an upload URL requires the
  * same gRPC authorization as push; download keys are unguessable content
  * hashes handed out by authorized skill reads.
  *
  * The lane slots into the transport's existing skillTransferLane seam
  * (transport/server.ts lane 3); URL renderers live next to the route
  * dispatch so the URL shape and its handler cannot drift apart (Go's
- * stated invariant). Proven by __tests__/skill.test.ts's transfer-lane
- * block (both protocol stacks) and the conformance suite's transfer-lane
- * tests.
+ * stated invariant): uploadUrl is what the local driver's staged-upload
+ * lane mints, and transferServeUrl is the serve URL the composition hands
+ * the local skill driver so its signed GETs land on the download route
+ * below. Proven by __tests__/skill.test.ts's transfer-lane block (both
+ * protocol stacks) and the conformance suite's transfer-lane tests.
  */
 import type { Logger } from "../../../boot/logger.js";
 import { SKILL_ARTIFACTS_PATH_PREFIX } from "../../../transport/constants.js";
@@ -32,6 +36,7 @@ import {
   SlotUnknownError,
 } from "./slots.js";
 import type { UploadSlots } from "./slots.js";
+import { stagingKeyOf } from "./staging.js";
 
 /**
  * Renders the capability URL for a minted reference against the lane's
@@ -41,9 +46,13 @@ export function uploadUrl(baseUrl: string, ref: string): string {
   return `${trimTrailingSlash(baseUrl)}${SKILL_ARTIFACTS_PATH_PREFIX}${UPLOADS_SEGMENT}${ref}`;
 }
 
-/** Renders the download URL for an artifact storage key. */
-export function downloadUrl(baseUrl: string, storageKey: string): string {
-  return `${trimTrailingSlash(baseUrl)}${SKILL_ARTIFACTS_PATH_PREFIX}/${storageKey}`;
+/**
+ * The lane's download origin: the local skill driver's serve URL, so that
+ * `${serveUrl}/${storageKey}` (LocalArtifactStorage.getSignedUrl's shape)
+ * is exactly the GET route this handler dispatches.
+ */
+export function transferServeUrl(baseUrl: string): string {
+  return `${trimTrailingSlash(baseUrl)}${SKILL_ARTIFACTS_PATH_PREFIX}`;
 }
 
 function trimTrailingSlash(url: string): string {
@@ -108,16 +117,25 @@ async function handleUpload(
     return;
   }
 
+  // Deliberately one shape for "malformed", "never existed" and "expired":
+  // distinguishing them would let an unauthorized caller probe which
+  // tokens were once valid.
+  const unknown = () =>
+    writeText(response, 404, "upload reference unknown or expired — request a new upload URL");
+
+  const key = stagingKeyOf(ref);
+  if (key === undefined) {
+    unknown();
+    return;
+  }
+
   try {
-    await slots.receive(ref, request);
+    await slots.receive(key, request);
     response.statusCode = 204;
     response.end();
   } catch (error) {
     if (error instanceof SlotUnknownError) {
-      // Deliberately the same shape for "never existed" and "expired":
-      // distinguishing them would let an unauthorized caller probe which
-      // tokens were once valid.
-      writeText(response, 404, "upload reference unknown or expired — request a new upload URL");
+      unknown();
     } else if (error instanceof SlotConsumedError) {
       writeText(response, 409, "upload reference already used — request a new upload URL");
     } else if (error instanceof SizeMismatchError) {

package/src/domain/skill/transfer/slots.ts

@@ -1,9 +1,18 @@
 /**
- * Skill artifact upload slots — ports pkg/domain/skill/transfer/slots.go.
- * The in-memory registry of single-use upload capabilities plus the
- * staging directory their bytes land in (#675).
+ * Skill artifact upload slots — the local blob driver's staging mechanism,
+ * ported from pkg/domain/skill/transfer/slots.go: an in-memory registry of
+ * single-use upload capabilities plus the staging files their bytes land
+ * in (#675).
  *
- * In-memory is deliberate: the OSS server is single-instance (the same
+ * A slot is keyed by the STAGING KEY the domain names (`skills/staging/
+ * <hex>.zip`, transfer/staging.ts), and its file is that key resolved
+ * under the blob driver's root — so the driver's own download(key) reads
+ * what the lane received and its delete(key) retires the bytes, exactly
+ * as a bucket driver's would. The registry therefore knows nothing of
+ * consumption: it reserves, receives, and sweeps; the domain reads and
+ * deletes through the driver, one path for every backend.
+ *
+ * In-memory is deliberate: the local driver is single-instance (the same
  * assumption the in-process router transport and SQLite store already
  * make), and a slot is worthless across restarts anyway — its bytes live
  * in the staging directory, which is swept on boot.
@@ -11,20 +20,16 @@
  * Sentinel error classes replace Go's sentinel error values so the HTTP
  * handler maps registry failures onto honest status codes without string
  * matching; their message texts are Go's, verbatim (they ride wire-visible
- * copy: push's "artifact_upload_ref not usable: %v" and the handler's 400
- * body).
+ * copy: the handler's 404, 409 and 400 bodies).
  *
  * Proven by __tests__/slots.test.ts (injected clock for expiry) and the
  * conformance suite's transfer-lane tests.
  */
-import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
 import type { Readable } from "node:stream";
 
-import { REF_BYTE_LEN, REF_PREFIX } from "../constants.js";
-
 /** Go errSlotUnknown — never existed, expired, or swept. */
 export class SlotUnknownError extends Error {
   constructor() {
@@ -41,18 +46,12 @@ export class SlotConsumedError extends Error {
   }
 }
 
-/** Go errSlotEmpty — minted but never (successfully) uploaded to. */
-export class SlotEmptyError extends Error {
-  constructor() {
-    super("upload reference has no uploaded bytes");
-    this.name = "SlotEmptyError";
-  }
-}
-
-/** Go errSizeMismatch — the body disagreed with the minted declaration. */
+/** Go errSizeMismatch — the body disagreed with the reserved declaration. */
 export class SizeMismatchError extends Error {
   constructor(received: number, declared: number) {
-    super(`upload size mismatch: received ${received} bytes, declared ${declared}`);
+    super(
+      `upload size mismatch: received ${received} bytes, declared ${declared}`,
+    );
     this.name = "SizeMismatchError";
   }
 }
@@ -63,65 +62,76 @@ interface Slot {
   uploaded: boolean;
 }
 
+/**
+ * The one file-name shape a staging key may carry past its prefix: the
+ * domain's hex reference plus the archive suffix. Keys are server-minted,
+ * never client-supplied, so this is an invariant check, not input
+ * validation — a violation is a programming error and throws.
+ */
+const STAGED_FILE_NAME = /^[0-9a-f]+\.zip$/;
+
 export class UploadSlots {
   private readonly slots = new Map<string, Slot>();
   private readonly stagingDir: string;
-  private readonly ttlMs: number;
-  private readonly maxSize: number;
   /** Injectable for expiry tests, mirroring Go's `now` field. */
   private readonly now: () => number;
 
   /**
-   * Creates the registry and prepares the staging directory. Any file
-   * already present is an orphan from a previous process (the registry
-   * that knew about it died with that process), so the directory is
-   * emptied — this is also the crash-recovery story for uploads that
-   * never reached their push.
+   * Creates the registry over `root` (the local blob driver's root) and
+   * prepares the staging directory `root/stagingPrefix`. Any file already
+   * present is an orphan from a previous process (the registry that knew
+   * about it died with that process), so the directory is emptied — this
+   * is also the crash-recovery story for uploads that never reached their
+   * push.
    */
   constructor(
-    stagingDir: string,
-    ttlMs: number,
-    maxSize: number,
+    private readonly root: string,
+    private readonly stagingPrefix: string,
+    private readonly ttlMs: number,
+    private readonly maxSize: number,
     now: () => number = Date.now,
   ) {
-    fs.rmSync(stagingDir, { recursive: true, force: true });
-    fs.mkdirSync(stagingDir, { recursive: true, mode: 0o700 });
-    this.stagingDir = stagingDir;
-    this.ttlMs = ttlMs;
-    this.maxSize = maxSize;
+    this.stagingDir = path.join(root, stagingPrefix);
+    fs.rmSync(this.stagingDir, { recursive: true, force: true });
+    fs.mkdirSync(this.stagingDir, { recursive: true, mode: 0o700 });
     this.now = now;
   }
 
   /**
-   * Reserves an upload slot for an artifact of declaredSize bytes and
-   * returns its single-use reference + TTL. The caller has already
+   * Reserves an upload slot for an artifact of declaredSize bytes at the
+   * staging key; returns the TTL granted. The caller has already
    * authorized the request and validated declaredSize against the skill
-   * size limit; this guard is the registry's own invariant.
+   * size limit; the bound here is the registry's own invariant.
    */
-  mint(declaredSize: number): { ref: string; ttlMs: number } {
+  reserve(key: string, declaredSize: number): { ttlMs: number } {
     if (declaredSize <= 0 || declaredSize > this.maxSize) {
-      throw new Error(`declared size ${declaredSize} outside (0, ${this.maxSize}]`);
+      throw new Error(
+        `declared size ${declaredSize} outside (0, ${this.maxSize}]`,
+      );
+    }
+    this.stagePath(key);
+    if (this.slots.has(key)) {
+      throw new Error(`staging key ${key} is already reserved`);
     }
-    const ref = REF_PREFIX + randomBytes(REF_BYTE_LEN).toString("hex");
     this.sweep();
-    this.slots.set(ref, {
+    this.slots.set(key, {
       declaredSize,
       expiresAtMs: this.now() + this.ttlMs,
       uploaded: false,
     });
-    return { ref, ttlMs: this.ttlMs };
+    return { ttlMs: this.ttlMs };
   }
 
   /**
    * Streams an upload's body into the slot's staging file. The body must
-   * match the size declared at mint time exactly: a shorter body means a
+   * match the size declared at reservation exactly: a shorter body means a
    * truncated transfer, a longer one means the client lied — both reject
    * rather than staging bytes that would fail (or worse, surprise)
-   * validation later. The staged file only becomes consumable once this
-   * resolves.
+   * validation later. The staged file only becomes readable through the
+   * driver once this resolves.
    */
-  async receive(ref: string, body: Readable): Promise<void> {
-    const slot = this.slots.get(ref);
+  async receive(key: string, body: Readable): Promise<void> {
+    const slot = this.slots.get(key);
     if (slot === undefined || this.now() > slot.expiresAtMs) {
       throw new SlotUnknownError();
     }
@@ -130,9 +140,16 @@ export class UploadSlots {
     }
     const declared = slot.declaredSize;
 
-    const filePath = this.stagePath(ref);
+    const filePath = this.stagePath(key);
     let written = 0;
     try {
+      // The driver's delete(key) prunes directories it empties, so the
+      // staging directory may be gone between two uploads; recreate it
+      // rather than fail the second one.
+      await fs.promises.mkdir(path.dirname(filePath), {
+        recursive: true,
+        mode: 0o700,
+      });
       // Consume at most declared+1 bytes: seeing the extra byte proves the
       // body exceeds the declaration without buffering an unbounded stream
       // (Go's io.LimitReader(declared+1) + written != declared check).
@@ -157,7 +174,7 @@ export class UploadSlots {
 
     // Re-check after the write: the slot may have expired mid-upload
     // (Go re-checks under the lock for the same reason).
-    const current = this.slots.get(ref);
+    const current = this.slots.get(key);
     if (current === undefined || this.now() > current.expiresAtMs) {
       await fs.promises.rm(filePath, { force: true });
       throw new SlotUnknownError();
@@ -166,66 +183,35 @@ export class UploadSlots {
   }
 
   /**
-   * Returns the staged bytes for ref and retires the slot — an upload
-   * reference is strictly single-use. Push calls this when it sees
-   * artifact_upload_ref; whatever happens downstream (validation failure
-   * included), the slot is gone and the client must re-mint to retry.
-   */
-  async consume(ref: string): Promise<Uint8Array> {
-    const slot = this.slots.get(ref);
-    if (slot === undefined || this.now() > slot.expiresAtMs) {
-      throw new SlotUnknownError();
-    }
-    if (!slot.uploaded) {
-      throw new SlotEmptyError();
-    }
-    this.slots.delete(ref);
-
-    const filePath = this.stagePath(ref);
-    try {
-      const data = await fs.promises.readFile(filePath);
-      return data;
-    } catch (error) {
-      throw new Error(
-        `failed to read staged artifact: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    } finally {
-      await fs.promises.rm(filePath, { force: true });
-    }
-  }
-
-  /**
-   * Drops expired slots and their staged files. Called from mint, which
-   * bounds the registry: it can hold at most the slots minted within one
+   * Drops expired slots and their staged files. Called from reserve, which
+   * bounds the registry: it can hold at most the slots reserved within one
    * TTL window.
    */
   private sweep(): void {
     const nowMs = this.now();
-    for (const [ref, slot] of this.slots) {
+    for (const [key, slot] of this.slots) {
       if (nowMs > slot.expiresAtMs) {
-        this.slots.delete(ref);
-        fs.rmSync(this.stagePath(ref), { force: true });
+        this.slots.delete(key);
+        fs.rmSync(this.stagePath(key), { force: true });
       }
     }
   }
 
   /**
-   * The staging file name for a reference. Public since O5: the local
-   * driver's presigned-PUT arm maps refs onto driver staging keys
-   * (boot/compose.ts), and that mapping must come from HERE — a
-   * re-declared "<ref>.zip" in the composition would drift from stagePath
-   * with nothing to catch it.
-   */
-  stagedFileName(ref: string): string {
-    return `${ref}.zip`;
-  }
-
-  /**
-   * Maps a reference to its staging file. refs are server-generated hex
-   * (never client-supplied paths), so simple joining is safe.
+   * Maps a staging key to its file: the key resolved under the driver's
+   * root, which is how the driver's download(key) will look for it. The
+   * key must carry the staging prefix and a plain hex file name — anything
+   * else is a caller bug, refused before it touches the filesystem.
    */
-  private stagePath(ref: string): string {
-    return path.join(this.stagingDir, this.stagedFileName(ref));
+  private stagePath(key: string): string {
+    if (!key.startsWith(this.stagingPrefix)) {
+      throw new Error(`staging key ${key} is outside ${this.stagingPrefix}`);
+    }
+    const fileName = key.slice(this.stagingPrefix.length);
+    if (!STAGED_FILE_NAME.test(fileName)) {
+      throw new Error(`staging key ${key} does not name a staged archive`);
+    }
+    return path.join(this.root, key);
   }
 }
 
@@ -238,13 +224,16 @@ function limitBytes(
   limit: number,
   onBytes: (count: number) => void,
 ): (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer> {
-  return async function* (source: AsyncIterable<Buffer>): AsyncIterable<Buffer> {
+  return async function* (
+    source: AsyncIterable<Buffer>,
+  ): AsyncIterable<Buffer> {
     let remaining = limit;
     for await (const chunk of source) {
       if (remaining <= 0) {
         return;
       }
-      const slice = chunk.length <= remaining ? chunk : chunk.subarray(0, remaining);
+      const slice =
+        chunk.length <= remaining ? chunk : chunk.subarray(0, remaining);
       remaining -= slice.length;
       onBytes(slice.length);
       yield slice;