@stigmer/server 3.22.1 → 3.23.0

package/src/domain/skill/__tests__/staging.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Pins the archive staging port (transfer/staging.ts): the reference ⇄
+ * staging-key mapping and its refusals; mint handing the driver the
+ * domain's key and the slot TTL; consume reading then deleting, with the
+ * delete best-effort and loud; the one "unknown or expired" condition for
+ * a malformed, missing or already-consumed reference; a driver fault
+ * propagating untouched; the download capability's floor TTL. First over
+ * a recording fake driver (what any bucket sees), then over the real local
+ * driver with its slot registry, wired exactly as boot/compose.ts wires it
+ * — the two drivers must be indistinguishable above this module.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  ArtifactStorageNotFoundError,
+  LocalArtifactStorage,
+} from "../../../artifactstorage/artifact-storage.js";
+import type { ArtifactStorage } from "../../../artifactstorage/artifact-storage.js";
+import { createLogger } from "../../../boot/logger.js";
+import { SKILL_ARTIFACTS_PATH_PREFIX } from "../../../transport/constants.js";
+import {
+  DEFAULT_SLOT_TTL_MS,
+  DOWNLOAD_URL_TTL_MS,
+  MAX_ZIP_SIZE,
+  STAGING_KEY_PREFIX,
+  UPLOADS_SEGMENT,
+} from "../constants.js";
+import { transferServeUrl, uploadUrl } from "../transfer/handler.js";
+import { SlotUnknownError, UploadSlots } from "../transfer/slots.js";
+import {
+  newArchiveStaging,
+  newUploadRef,
+  stagingKeyOf,
+  uploadRefOf,
+} from "../transfer/staging.js";
+import type { ArchiveStaging } from "../transfer/staging.js";
+
+const logLines: string[] = [];
+const logger = createLogger({
+  level: "error",
+  pretty: false,
+  write: (line) => {
+    logLines.push(line);
+  },
+});
+
+describe("the reference ⇄ staging key mapping", () => {
+  it("mints sau_-prefixed 128-bit hex references whose key sits under the staging prefix", () => {
+    const ref = newUploadRef();
+    expect(ref).toMatch(/^sau_[0-9a-f]{32}$/);
+    const key = stagingKeyOf(ref);
+    expect(key).toBe(`${STAGING_KEY_PREFIX}${ref.slice(4)}.zip`);
+    expect(uploadRefOf(key!)).toBe(ref);
+  });
+
+  it("answers no key for a reference this server could not have minted", () => {
+    for (const bad of [
+      "",
+      "sau_",
+      "sau_nope",
+      "sau_" + "g".repeat(32),
+      "sau_" + "0".repeat(31),
+      "skl_" + "0".repeat(32),
+      "sau_" + "A".repeat(32),
+    ]) {
+      expect(stagingKeyOf(bad), bad).toBeUndefined();
+    }
+  });
+
+  it("refuses to derive a reference from a foreign key", () => {
+    expect(() => uploadRefOf("skills/deadbeef.zip")).toThrow(
+      "is not a staging key this domain minted",
+    );
+    expect(() => uploadRefOf(`${STAGING_KEY_PREFIX}notes.txt`)).toThrow(
+      "is not a staging key this domain minted",
+    );
+  });
+});
+
+// ─── Over a recording fake: what a bucket driver is asked to do ──────────
+
+interface Recorded {
+  presignPut: Array<{ key: string; declaredSizeBytes: number; ttlMs: number }>;
+  downloads: string[];
+  deletes: string[];
+  signed: Array<{ key: string; expiresInMs: number; downloadFilename: string }>;
+}
+
+function fakeDriver(
+  options: { failDelete?: boolean; failDownload?: Error } = {},
+): {
+  driver: ArtifactStorage;
+  blobs: Map<string, Uint8Array>;
+  recorded: Recorded;
+} {
+  const blobs = new Map<string, Uint8Array>();
+  const recorded: Recorded = {
+    presignPut: [],
+    downloads: [],
+    deletes: [],
+    signed: [],
+  };
+  const driver: ArtifactStorage = {
+    upload: (key, data) => {
+      blobs.set(key, data);
+      return Promise.resolve();
+    },
+    download: (key) => {
+      recorded.downloads.push(key);
+      if (options.failDownload) return Promise.reject(options.failDownload);
+      const data = blobs.get(key);
+      return data === undefined
+        ? Promise.reject(new ArtifactStorageNotFoundError(key))
+        : Promise.resolve(data);
+    },
+    size: (key) => Promise.resolve(blobs.get(key)?.length ?? 0),
+    presignPut: (key, declaredSizeBytes, ttlMs) => {
+      recorded.presignPut.push({ key, declaredSizeBytes, ttlMs });
+      return Promise.resolve({
+        url: `https://bucket.test/${key}?sig=put`,
+        ttlMs: ttlMs / 2,
+      });
+    },
+    getSignedUrl: (key, expiresInMs, downloadFilename) => {
+      recorded.signed.push({ key, expiresInMs, downloadFilename });
+      return Promise.resolve(`https://bucket.test/${key}?sig=get`);
+    },
+    delete: (key) => {
+      recorded.deletes.push(key);
+      if (options.failDelete)
+        return Promise.reject(new Error("bucket refused the delete"));
+      blobs.delete(key);
+      return Promise.resolve();
+    },
+    exists: (key) => Promise.resolve(blobs.has(key)),
+    health: () => Promise.resolve(),
+  };
+  return { driver, blobs, recorded };
+}
+
+describe("newArchiveStaging over a bucket-shaped driver", () => {
+  beforeEach(() => {
+    logLines.length = 0;
+  });
+
+  it("mint hands the driver the domain's key and the slot TTL, and returns the driver's URL and granted TTL", async () => {
+    const { driver, recorded } = fakeDriver();
+    const staging = newArchiveStaging(driver, logger);
+    const minted = await staging.mint(1234);
+
+    expect(recorded.presignPut).toEqual([
+      {
+        key: stagingKeyOf(minted.ref),
+        declaredSizeBytes: 1234,
+        ttlMs: DEFAULT_SLOT_TTL_MS,
+      },
+    ]);
+    expect(minted.url).toBe(
+      `https://bucket.test/${stagingKeyOf(minted.ref)}?sig=put`,
+    );
+    expect(minted.ttlMs).toBe(DEFAULT_SLOT_TTL_MS / 2);
+  });
+
+  it("mint refuses a declaration outside the archive ceiling before any driver call", async () => {
+    const { driver, recorded } = fakeDriver();
+    const staging = newArchiveStaging(driver, logger);
+    await expect(staging.mint(0)).rejects.toThrow(
+      `declared size 0 outside (0, ${MAX_ZIP_SIZE}]`,
+    );
+    await expect(staging.mint(MAX_ZIP_SIZE + 1)).rejects.toThrow("outside");
+    expect(recorded.presignPut).toEqual([]);
+  });
+
+  it("consume reads the staged key, deletes it, and a replay is unknown", async () => {
+    const { driver, blobs, recorded } = fakeDriver();
+    const staging = newArchiveStaging(driver, logger);
+    const minted = await staging.mint(5);
+    const key = stagingKeyOf(minted.ref)!;
+    blobs.set(key, Buffer.from("hello"));
+
+    expect(Buffer.from(await staging.consume(minted.ref)).toString()).toBe(
+      "hello",
+    );
+    expect(recorded.downloads).toEqual([key]);
+    expect(recorded.deletes).toEqual([key]);
+    await expect(staging.consume(minted.ref)).rejects.toThrow(SlotUnknownError);
+  });
+
+  it("a malformed or never-uploaded reference is one condition: unknown or expired", async () => {
+    const { driver, recorded } = fakeDriver();
+    const staging = newArchiveStaging(driver, logger);
+    await expect(staging.consume("not-a-ref")).rejects.toThrow(
+      "upload reference unknown or expired",
+    );
+    // Nothing shaped like a key reaches the driver for a malformed ref.
+    expect(recorded.downloads).toEqual([]);
+
+    const minted = await staging.mint(5);
+    await expect(staging.consume(minted.ref)).rejects.toThrow(SlotUnknownError);
+  });
+
+  it("a failed delete is loud and does not fail the consume", async () => {
+    const { driver, blobs } = fakeDriver({ failDelete: true });
+    const staging = newArchiveStaging(driver, logger);
+    const minted = await staging.mint(5);
+    blobs.set(stagingKeyOf(minted.ref)!, Buffer.from("hello"));
+
+    expect(Buffer.from(await staging.consume(minted.ref)).toString()).toBe(
+      "hello",
+    );
+    expect(
+      logLines.some((line) =>
+        line.includes("failed to delete consumed staged artifact"),
+      ),
+    ).toBe(true);
+  });
+
+  it("a driver fault on download propagates as itself, never as an unusable reference", async () => {
+    const fault = new Error("bucket unreachable");
+    const { driver } = fakeDriver({ failDownload: fault });
+    const staging = newArchiveStaging(driver, logger);
+    const minted = await staging.mint(5);
+    await expect(staging.consume(minted.ref)).rejects.toBe(fault);
+  });
+
+  it("downloadUrl signs the stored key for the floor TTL and reports it", async () => {
+    const { driver, recorded } = fakeDriver();
+    const staging = newArchiveStaging(driver, logger);
+    const capability = await staging.downloadUrl("skills/abc.zip");
+    expect(recorded.signed).toEqual([
+      {
+        key: "skills/abc.zip",
+        expiresInMs: DOWNLOAD_URL_TTL_MS,
+        downloadFilename: "",
+      },
+    ]);
+    expect(capability).toEqual({
+      url: "https://bucket.test/skills/abc.zip?sig=get",
+      ttlMs: DOWNLOAD_URL_TTL_MS,
+    });
+  });
+});
+
+// ─── Over the real local driver: the slot registry behind the same port ──
+
+describe("newArchiveStaging over LocalArtifactStorage and its slot registry", () => {
+  const BASE_URL = "http://localhost:8080";
+  let root: string;
+  let slots: UploadSlots;
+  let staging: ArchiveStaging;
+
+  beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), "archive-staging-local-"));
+    slots = new UploadSlots(root, STAGING_KEY_PREFIX, 60_000, 1024 * 1024);
+    const driver = new LocalArtifactStorage(root, transferServeUrl(BASE_URL), {
+      reserve: (key, declaredSizeBytes) => {
+        const { ttlMs } = slots.reserve(key, declaredSizeBytes);
+        return { url: uploadUrl(BASE_URL, uploadRefOf(key)), ttlMs };
+      },
+    });
+    staging = newArchiveStaging(driver, logger);
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("mint → lane receive → consume round-trips the bytes and retires the reference", async () => {
+    const bytes = Buffer.from("staged artifact bytes");
+    const minted = await staging.mint(bytes.length);
+
+    // The URL is the lane's wire shape and the ref is its last segment —
+    // exactly how the lane handler dispatches a PUT.
+    expect(minted.url).toBe(
+      `${BASE_URL}${SKILL_ARTIFACTS_PATH_PREFIX}${UPLOADS_SEGMENT}${minted.ref}`,
+    );
+    // The registry's slot TTL governs, not the domain's ask.
+    expect(minted.ttlMs).toBe(60_000);
+
+    await slots.receive(stagingKeyOf(minted.ref)!, Readable.from(bytes));
+    expect(Buffer.from(await staging.consume(minted.ref))).toEqual(bytes);
+    await expect(staging.consume(minted.ref)).rejects.toThrow(SlotUnknownError);
+  });
+
+  it("a reserved-but-never-uploaded reference is unknown, exactly as on a bucket", async () => {
+    const minted = await staging.mint(4);
+    await expect(staging.consume(minted.ref)).rejects.toThrow(
+      "upload reference unknown or expired",
+    );
+  });
+
+  it("downloadUrl renders the lane's own GET route with the floor TTL", async () => {
+    const capability = await staging.downloadUrl("skills/abc.zip");
+    expect(capability).toEqual({
+      url: `${BASE_URL}${SKILL_ARTIFACTS_PATH_PREFIX}/skills/abc.zip`,
+      ttlMs: DOWNLOAD_URL_TTL_MS,
+    });
+  });
+});

package/src/domain/skill/constants.ts

@@ -27,10 +27,34 @@ export const MAX_SKILL_MD_SIZE = 1 * 1024 * 1024;
 /**
  * Upload-slot lifetime — generous enough for a 100MB upload on a slow
  * link, short enough that abandoned slots don't accumulate. Go:
- * transfer.DefaultSlotTTL (15 minutes).
+ * transfer.DefaultSlotTTL (15 minutes). The same lifetime is asked of a
+ * bucket driver's presigned PUT, so the reference and the URL it names
+ * expire together whichever driver serves them.
  */
 export const DEFAULT_SLOT_TTL_MS = 15 * 60 * 1000;
 
+/**
+ * Download capability lifetime — the floor of a minted download URL's
+ * validity, reported as ttl_seconds. A bucket driver signs its GET for
+ * exactly this long, the lifetime the cloud edition already grants
+ * execution-artifact downloads; the local lane's URL is a content-hash
+ * capability that never expires, so the floor holds there trivially. An
+ * hour outlives any mount the runner performs while staying short enough
+ * that a leaked URL is not a standing grant.
+ */
+export const DOWNLOAD_URL_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Where staged uploads live in the blob store, under the skill store's own
+ * prefix: `skills/staging/<hex>.zip`. The retired cloud service staged
+ * under this exact prefix, so the bucket lifecycle rule that sweeps
+ * abandoned uploads is written for it, and on the local driver the boot
+ * wipe targets the same directory. Every staged object is a random
+ * 128-bit key, so its exposure through the download lane is the same
+ * capability the upload reference already grants.
+ */
+export const STAGING_KEY_PREFIX = "skills/staging/";
+
 /**
  * Random capability-token size: 16 bytes = 128 bits of entropy, matching
  * the unguessability of the content-hash download keys. Go: refByteLen.
@@ -53,8 +77,9 @@ export const UPLOADS_SEGMENT = "/uploads/";
 
 /**
  * Downloads are restricted to the skill artifact store's own keys
- * ("skills/<hash>.zip"); everything else under the storage root — should
- * the two ever share one — stays unreachable from this lane.
+ * ("skills/<hash>.zip", and the staged uploads under STAGING_KEY_PREFIX);
+ * everything else under the storage root — should the two ever share one
+ * — stays unreachable from this lane.
  */
 export const DOWNLOAD_KEY_PREFIX = "skills/";
 

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.
@@ -119,8 +121,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 +141,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 +156,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 +221,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 +265,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 +307,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),
   });
@@ -738,17 +738,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 +786,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) {