@stigmer/server 3.22.1 → 3.23.1-dev.20260923075205

package/src/domain/session/controller.ts

@@ -85,7 +85,10 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
-import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
+import {
+  newNormalizeReferencesStep,
+  newValidateReferencesStep,
+} from "../../pipeline/steps/references.js";
 import {
   newCleanupIamPoliciesStep,
   newCreateAuthorizationTuplesStep,
@@ -208,7 +211,8 @@ async function createSession(
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
-    .addStep(newNormalizeReferencesStep());
+    .addStep(newNormalizeReferencesStep())
+    .addStep(newValidateReferencesStep(deps.store));
   // The ratified pre-side-effect gate slot (blueprint 03 §3a; O4; Q2
   // ruling — see the create doc comment). Empty in OSS.
   for (const step of stepsForSlot<typeof SessionSchema>(
@@ -499,7 +503,9 @@ async function list(
       newAuthorizeStep(SessionQueryController.method.list, deps.authorizer),
     )
     .addStep(newValidateProtoStep())
-    .addStep(newListAllSessionsStep(deps.store, deps.logger, deps.listReadScope))
+    .addStep(
+      newListAllSessionsStep(deps.store, deps.logger, deps.listReadScope),
+    )
     .build()
     .execute(reqCtx);
   return requireListResult(reqCtx.get(LIST_RESULT_KEY));
@@ -559,7 +565,9 @@ async function listByChannel(
     )
     .addStep(newValidateProtoStep())
     .addStep(newAuthorizeChannelAccessStep(deps.authorizer))
-    .addStep(newFilterByChannelStep(deps.store, deps.logger, deps.listReadScope))
+    .addStep(
+      newFilterByChannelStep(deps.store, deps.logger, deps.listReadScope),
+    )
     .build()
     .execute(reqCtx);
   return requireListResult(reqCtx.get(LIST_RESULT_KEY));

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

@@ -434,7 +434,7 @@ describe("transfer lane (#675) — mint → PUT → push-by-ref → download", (
     );
   });
 
-  it("a ref whose slot was minted but never uploaded is rejected at push", async () => {
+  it("a ref whose slot was minted but never uploaded is rejected at push — the one condition every driver can answer", async () => {
     const minted = await command.createArtifactUploadUrl({ org: ORG, sizeBytes: 1024n });
     const err = await expectCode(
       command.push({ org: ORG, artifactUploadRef: minted.artifactUploadRef }),
@@ -442,7 +442,7 @@ describe("transfer lane (#675) — mint → PUT → push-by-ref → download", (
       "empty slot",
     );
     expect(err.rawMessage).toBe(
-      "artifact_upload_ref not usable: upload reference has no uploaded bytes — request a new upload URL via createArtifactUploadUrl",
+      "artifact_upload_ref not usable: upload reference unknown or expired — request a new upload URL via createArtifactUploadUrl",
     );
   });
 
@@ -499,7 +499,9 @@ describe("transfer lane (#675) — mint → PUT → push-by-ref → download", (
     const minted = await query.getArtifactDownloadUrl({
       artifactStorageKey: pushed.status!.artifactStorageKey,
     });
-    expect(minted.ttlSeconds).toBe(0);
+    // The floor of the URL's validity, the same on every driver; the local
+    // lane's content-hash URL simply outlives it.
+    expect(minted.ttlSeconds).toBe(3600);
     expect(minted.sizeBytes).toBe(BigInt(artifact.length));
 
     const resp = await fetch(minted.url);

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

@@ -1,28 +1,39 @@
 /**
- * Pins the upload-slot registry against Go's slots_test.go: mint bounds,
- * ref shape, TTL expiry (injected clock), exact-declared-size enforcement
- * (short AND long bodies), strict single-use consume, staged-file cleanup,
- * expiry sweep on mint, and the boot-time staging wipe.
+ * Pins the upload-slot registry against Go's slots_test.go, keyed by the
+ * domain's staging key: reservation bounds and key shape, TTL expiry
+ * (injected clock), exact-declared-size enforcement (short AND long
+ * bodies), single upload per key, staged-file placement under the driver
+ * root, expiry sweep on reservation, the boot-time staging wipe, and the
+ * staging directory's recreation after the driver's delete pruned it.
  */
-import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} 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 { STAGING_KEY_PREFIX } from "../constants.js";
 import {
   SizeMismatchError,
   SlotConsumedError,
-  SlotEmptyError,
   SlotUnknownError,
   UploadSlots,
 } from "../transfer/slots.js";
+import { newUploadRef, stagingKeyOf } from "../transfer/staging.js";
 
 const TTL_MS = 15 * 60 * 1000;
 const MAX_SIZE = 100 * 1024 * 1024;
 
-let dir: string;
+let root: string;
 let stagingDir: string;
 let nowMs: number;
 let slots: UploadSlots;
@@ -31,101 +42,143 @@ function body(text: string): Readable {
   return Readable.from([Buffer.from(text)]);
 }
 
+/** A fresh, well-formed staging key — what the domain's mint hands the registry. */
+function freshKey(): string {
+  const key = stagingKeyOf(newUploadRef());
+  if (key === undefined) throw new Error("a minted ref always has a key");
+  return key;
+}
+
 beforeEach(() => {
-  dir = mkdtempSync(path.join(tmpdir(), "skill-slots-test-"));
-  stagingDir = path.join(dir, "skills-staging");
+  root = mkdtempSync(path.join(tmpdir(), "skill-slots-test-"));
+  stagingDir = path.join(root, STAGING_KEY_PREFIX);
   nowMs = 1_000_000;
-  slots = new UploadSlots(stagingDir, TTL_MS, MAX_SIZE, () => nowMs);
+  slots = new UploadSlots(
+    root,
+    STAGING_KEY_PREFIX,
+    TTL_MS,
+    MAX_SIZE,
+    () => nowMs,
+  );
 });
 
 afterEach(() => {
-  rmSync(dir, { recursive: true, force: true });
+  rmSync(root, { recursive: true, force: true });
 });
 
 describe("UploadSlots", () => {
-  it("mints sau_-prefixed 128-bit hex refs with the registry TTL", () => {
-    const { ref, ttlMs } = slots.mint(1024);
-    expect(ref).toMatch(/^sau_[0-9a-f]{32}$/);
-    expect(ttlMs).toBe(TTL_MS);
+  it("reserves a key with the registry TTL", () => {
+    expect(slots.reserve(freshKey(), 1024)).toEqual({ ttlMs: TTL_MS });
   });
 
-  it("rejects out-of-bounds declarations at mint", () => {
-    expect(() => slots.mint(0)).toThrow("declared size 0 outside (0, 104857600]");
-    expect(() => slots.mint(-1)).toThrow(`declared size -1 outside (0, ${MAX_SIZE}]`);
-    expect(() => slots.mint(MAX_SIZE + 1)).toThrow(
+  it("rejects out-of-bounds declarations at reservation", () => {
+    expect(() => slots.reserve(freshKey(), 0)).toThrow(
+      "declared size 0 outside (0, 104857600]",
+    );
+    expect(() => slots.reserve(freshKey(), -1)).toThrow(
+      `declared size -1 outside (0, ${MAX_SIZE}]`,
+    );
+    expect(() => slots.reserve(freshKey(), MAX_SIZE + 1)).toThrow(
       `declared size ${MAX_SIZE + 1} outside (0, ${MAX_SIZE}]`,
     );
   });
 
-  it("round-trips: mint → receive → consume returns the exact bytes and retires the slot", async () => {
-    const { ref } = slots.mint(5);
-    await slots.receive(ref, body("hello"));
-    const data = await slots.consume(ref);
-    expect(Buffer.from(data).toString()).toBe("hello");
-    // Strictly single-use: the slot AND its staged file are gone.
-    await expect(slots.consume(ref)).rejects.toThrow(SlotUnknownError);
-    expect(readdirSync(stagingDir)).toEqual([]);
+  it("refuses a key outside the staging prefix or not shaped like a staged archive", () => {
+    expect(() => slots.reserve("skills/deadbeef.zip", 1)).toThrow(
+      `staging key skills/deadbeef.zip is outside ${STAGING_KEY_PREFIX}`,
+    );
+    expect(() =>
+      slots.reserve(`${STAGING_KEY_PREFIX}../escape.zip`, 1),
+    ).toThrow("does not name a staged archive");
+    expect(() => slots.reserve(`${STAGING_KEY_PREFIX}notes.txt`, 1)).toThrow(
+      "does not name a staged archive",
+    );
+  });
+
+  it("refuses to reserve the same key twice", () => {
+    const key = freshKey();
+    slots.reserve(key, 1);
+    expect(() => slots.reserve(key, 1)).toThrow(
+      `staging key ${key} is already reserved`,
+    );
+  });
+
+  it("stages a received body at the key under the root — where the driver reads it", async () => {
+    const key = freshKey();
+    slots.reserve(key, 5);
+    await slots.receive(key, body("hello"));
+    expect(readFileSync(path.join(root, key), "utf8")).toBe("hello");
   });
 
-  it("rejects receive on an unknown ref", async () => {
-    await expect(slots.receive("sau_nope", body("x"))).rejects.toThrow(SlotUnknownError);
+  it("rejects receive on an unreserved key", async () => {
+    await expect(slots.receive(freshKey(), body("x"))).rejects.toThrow(
+      SlotUnknownError,
+    );
   });
 
-  it("rejects receive on an expired ref", async () => {
-    const { ref } = slots.mint(1);
+  it("rejects receive on an expired key", async () => {
+    const key = freshKey();
+    slots.reserve(key, 1);
     nowMs += TTL_MS + 1;
-    await expect(slots.receive(ref, body("x"))).rejects.toThrow(SlotUnknownError);
+    await expect(slots.receive(key, body("x"))).rejects.toThrow(
+      SlotUnknownError,
+    );
   });
 
-  it("rejects a second upload to the same ref", async () => {
-    const { ref } = slots.mint(1);
-    await slots.receive(ref, body("x"));
-    await expect(slots.receive(ref, body("x"))).rejects.toThrow(SlotConsumedError);
+  it("rejects a second upload to the same key", async () => {
+    const key = freshKey();
+    slots.reserve(key, 1);
+    await slots.receive(key, body("x"));
+    await expect(slots.receive(key, body("x"))).rejects.toThrow(
+      SlotConsumedError,
+    );
   });
 
   it("rejects a short body, naming both sizes, and stages nothing", async () => {
-    const { ref } = slots.mint(10);
-    await expect(slots.receive(ref, body("short"))).rejects.toThrow(
+    const key = freshKey();
+    slots.reserve(key, 10);
+    await expect(slots.receive(key, body("short"))).rejects.toThrow(
       "upload size mismatch: received 5 bytes, declared 10",
     );
-    await expect(slots.receive(ref, body("short"))).rejects.toBeInstanceOf(SizeMismatchError);
+    await expect(slots.receive(key, body("short"))).rejects.toBeInstanceOf(
+      SizeMismatchError,
+    );
     expect(readdirSync(stagingDir)).toEqual([]);
   });
 
   it("rejects an over-declaration body without buffering it whole (declared+1 proof)", async () => {
-    const { ref } = slots.mint(3);
-    await expect(slots.receive(ref, body("longer than three"))).rejects.toThrow(
+    const key = freshKey();
+    slots.reserve(key, 3);
+    await expect(slots.receive(key, body("longer than three"))).rejects.toThrow(
       "upload size mismatch: received 4 bytes, declared 3",
     );
   });
 
-  it("rejects consume on a minted-but-never-uploaded ref", async () => {
-    const { ref } = slots.mint(1);
-    await expect(slots.consume(ref)).rejects.toThrow(SlotEmptyError);
-  });
-
-  it("rejects consume on an expired ref", async () => {
-    const { ref } = slots.mint(1);
-    await slots.receive(ref, body("x"));
-    nowMs += TTL_MS + 1;
-    await expect(slots.consume(ref)).rejects.toThrow(SlotUnknownError);
-  });
-
-  it("sweeps expired slots and their staged files on mint", async () => {
-    const { ref } = slots.mint(1);
-    await slots.receive(ref, body("x"));
+  it("sweeps expired slots and their staged files on reservation", async () => {
+    const key = freshKey();
+    slots.reserve(key, 1);
+    await slots.receive(key, body("x"));
     expect(readdirSync(stagingDir)).toHaveLength(1);
     nowMs += TTL_MS + 1;
-    slots.mint(1);
+    slots.reserve(freshKey(), 1);
     expect(readdirSync(stagingDir)).toEqual([]);
   });
 
+  it("recreates the staging directory when the driver's delete pruned it between uploads", async () => {
+    const key = freshKey();
+    slots.reserve(key, 1);
+    rmSync(stagingDir, { recursive: true, force: true });
+    await slots.receive(key, body("x"));
+    expect(readFileSync(path.join(root, key), "utf8")).toBe("x");
+  });
+
   it("wipes the staging directory at construction (orphans are unreachable)", () => {
-    const orphanDir = path.join(dir, "staging-with-orphans");
+    const orphanRoot = path.join(root, "orphan-root");
+    const orphanDir = path.join(orphanRoot, STAGING_KEY_PREFIX);
     mkdirSync(orphanDir, { recursive: true });
-    const orphan = path.join(orphanDir, "sau_orphan.zip");
+    const orphan = path.join(orphanDir, "deadbeef.zip");
     writeFileSync(orphan, "stale bytes");
-    new UploadSlots(orphanDir, TTL_MS, MAX_SIZE);
+    new UploadSlots(orphanRoot, STAGING_KEY_PREFIX, TTL_MS, MAX_SIZE);
     expect(existsSync(orphan)).toBe(false);
     expect(readdirSync(orphanDir)).toEqual([]);
   });

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/";