@stigmer/server 3.22.1 → 3.23.0

package/dist/domain/skill/transfer/slots.d.ts

@@ -7,72 +7,57 @@ export declare class SlotUnknownError extends Error {
 export declare class SlotConsumedError extends Error {
     constructor();
 }
-/** Go errSlotEmpty — minted but never (successfully) uploaded to. */
-export declare class SlotEmptyError extends Error {
-    constructor();
-}
-/** Go errSizeMismatch — the body disagreed with the minted declaration. */
+/** Go errSizeMismatch — the body disagreed with the reserved declaration. */
 export declare class SizeMismatchError extends Error {
     constructor(received: number, declared: number);
 }
 export declare class UploadSlots {
-    private readonly slots;
-    private readonly stagingDir;
+    private readonly root;
+    private readonly stagingPrefix;
     private readonly ttlMs;
     private readonly maxSize;
+    private readonly slots;
+    private readonly stagingDir;
     /** Injectable for expiry tests, mirroring Go's `now` field. */
     private readonly now;
     /**
-     * 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, now?: () => number);
+    constructor(root: string, stagingPrefix: string, ttlMs: number, maxSize: number, now?: () => number);
     /**
-     * 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;
+    reserve(key: string, declaredSize: number): {
         ttlMs: number;
     };
     /**
      * 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.
-     */
-    receive(ref: string, body: Readable): Promise<void>;
-    /**
-     * 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.
+     * validation later. The staged file only becomes readable through the
+     * driver once this resolves.
      */
-    consume(ref: string): Promise<Uint8Array>;
+    receive(key: string, body: Readable): Promise<void>;
     /**
-     * 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;
     /**
-     * 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;
-    /**
-     * 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;
 }

package/dist/domain/skill/transfer/slots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/slots.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,KAAK;;CAK1C;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C;AAED,qEAAqE;AACrE,qBAAa,cAAe,SAAQ,KAAK;;CAKxC;AAED,2EAA2E;AAC3E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI/C;AAQD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;;;OAMG;gBAED,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,MAAiB;IAU9B;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAc1D;;;;;;;OAOG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CzD;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuB/C;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAUb;;;;;;OAMG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAInC;;;OAGG;IACH,OAAO,CAAC,SAAS;CAGlB"}
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/slots.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,KAAK;;CAK1C;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C;AAED,6EAA6E;AAC7E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAM/C;AAgBD,qBAAa,WAAW;IAepB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjB1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;;;;OAOG;gBAEgB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAChC,GAAG,GAAE,MAAM,MAAiB;IAQ9B;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAmB7D;;;;;;;OAOG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDzD;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAUb;;;;;OAKG;IACH,OAAO,CAAC,SAAS;CAUlB"}

package/dist/domain/skill/transfer/slots.js

@@ -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,17 +20,14 @@
  * 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 { REF_BYTE_LEN, REF_PREFIX } from "../constants.js";
 /** Go errSlotUnknown — never existed, expired, or swept. */
 export class SlotUnknownError extends Error {
     constructor() {
@@ -36,71 +42,79 @@ export class SlotConsumedError extends Error {
         this.name = "SlotConsumedError";
     }
 }
-/** 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, declared) {
         super(`upload size mismatch: received ${received} bytes, declared ${declared}`);
         this.name = "SizeMismatchError";
     }
 }
+/**
+ * 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 {
-    slots = new Map();
-    stagingDir;
+    root;
+    stagingPrefix;
     ttlMs;
     maxSize;
+    slots = new Map();
+    stagingDir;
     /** Injectable for expiry tests, mirroring Go's `now` field. */
     now;
     /**
-     * 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, ttlMs, maxSize, now = Date.now) {
-        fs.rmSync(stagingDir, { recursive: true, force: true });
-        fs.mkdirSync(stagingDir, { recursive: true, mode: 0o700 });
-        this.stagingDir = stagingDir;
+    constructor(root, stagingPrefix, ttlMs, maxSize, now = Date.now) {
+        this.root = root;
+        this.stagingPrefix = stagingPrefix;
         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) {
+    reserve(key, declaredSize) {
         if (declaredSize <= 0 || declaredSize > this.maxSize) {
             throw new Error(`declared size ${declaredSize} outside (0, ${this.maxSize}]`);
         }
-        const ref = REF_PREFIX + randomBytes(REF_BYTE_LEN).toString("hex");
+        this.stagePath(key);
+        if (this.slots.has(key)) {
+            throw new Error(`staging key ${key} is already reserved`);
+        }
         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, body) {
-        const slot = this.slots.get(ref);
+    async receive(key, body) {
+        const slot = this.slots.get(key);
         if (slot === undefined || this.now() > slot.expiresAtMs) {
             throw new SlotUnknownError();
         }
@@ -108,9 +122,16 @@ export class UploadSlots {
             throw new SlotConsumedError();
         }
         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).
@@ -128,7 +149,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();
@@ -136,62 +157,34 @@ export class UploadSlots {
         current.uploaded = true;
     }
     /**
-     * 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) {
-        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.
      */
     sweep() {
         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.
+     * 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.
      */
-    stagedFileName(ref) {
-        return `${ref}.zip`;
-    }
-    /**
-     * Maps a reference to its staging file. refs are server-generated hex
-     * (never client-supplied paths), so simple joining is safe.
-     */
-    stagePath(ref) {
-        return path.join(this.stagingDir, this.stagedFileName(ref));
+    stagePath(key) {
+        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);
     }
 }
 /**

package/dist/domain/skill/transfer/slots.js.map

@@ -1 +1 @@
-{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/slots.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/slots.ts"],"names":[],"mappings":"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"}

package/dist/domain/skill/transfer/staging.d.ts

@@ -0,0 +1,48 @@
+import type { ArtifactStorage } from "../../../artifactstorage/artifact-storage.js";
+import type { Logger } from "../../../boot/logger.js";
+/** A fresh upload reference: the prefix and 128 random bits, hex. */
+export declare function newUploadRef(): string;
+/**
+ * The staging key a reference's bytes land under, or undefined when the
+ * reference is not one this server could have minted. Refs arrive from
+ * clients (the push request, the lane's URL path), so the shape is
+ * checked before it becomes a storage key.
+ */
+export declare function stagingKeyOf(ref: string): string | undefined;
+/**
+ * The reference for a staging key this module minted. Keys reach here from
+ * the domain's own mint, never from a client, so a foreign shape is a
+ * programming error and throws.
+ */
+export declare function uploadRefOf(stagingKey: string): string;
+/** What createArtifactUploadUrl hands the client. */
+export interface StagedUpload {
+    /** The single-use reference the push presents. */
+    readonly ref: string;
+    /** Accepts one HTTP PUT of exactly the declared byte count. */
+    readonly url: string;
+    /** How long the reference and the URL stay valid. */
+    readonly ttlMs: number;
+}
+/** What getArtifactDownloadUrl hands the client. */
+export interface DownloadCapability {
+    readonly url: string;
+    /** The floor of the URL's validity (DOWNLOAD_URL_TTL_MS). */
+    readonly ttlMs: number;
+}
+/** The staging port both archive kinds (skills, plugins) push through. */
+export interface ArchiveStaging {
+    /** Mints a reference and the URL its bytes are PUT to. */
+    mint(declaredSizeBytes: number): Promise<StagedUpload>;
+    /**
+     * Reads the staged bytes for a reference and retires it. Throws
+     * SlotUnknownError when the driver holds nothing under the reference;
+     * any other failure is the driver's and propagates as an infrastructure
+     * fault.
+     */
+    consume(ref: string): Promise<Uint8Array>;
+    /** A time-limited download URL for a stored archive key. */
+    downloadUrl(storageKey: string): Promise<DownloadCapability>;
+}
+export declare function newArchiveStaging(driver: ArtifactStorage, logger: Logger): ArchiveStaging;
+//# sourceMappingURL=staging.d.ts.map

package/dist/domain/skill/transfer/staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/staging.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAC;AAEpF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AA4BtD,qEAAqE;AACrE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,4DAA4D;IAC5D,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9D;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,GACb,cAAc,CA8DhB"}

package/dist/domain/skill/transfer/staging.js

@@ -0,0 +1,127 @@
+/**
+ * Archive staging — how an artifact above the gRPC message cap travels,
+ * on every blob driver, through one code path (#675, stigmer#1219).
+ *
+ * The domain owns the two identities and the mapping between them: the
+ * wire reference a client is handed (`sau_<hex>`, the capability the
+ * push presents) and the staging key the bytes land under in the blob
+ * store (`skills/staging/<hex>.zip`, the surface a sweep targets). A
+ * driver is asked only to sign or stage a PUT for a key it is given, to
+ * read the key back, and to delete it — so the local driver rides the
+ * transfer lane's slot registry and a bucket driver signs a PUT straight
+ * to the bucket, and nothing above this module can tell which.
+ *
+ * Consume reads then deletes: the delete is what keeps a reference
+ * single-use on a bucket, whose signed URL is otherwise repeatable within
+ * its TTL. The delete is best effort and loud — the bytes are already in
+ * hand, a replay of the same reference is a content-addressed no-op, and
+ * the bucket lifecycle rule on the staging prefix sweeps what the delete
+ * missed. On the local driver the same delete retires the staged file the
+ * slot registry would otherwise sweep at expiry.
+ *
+ * A reference the driver cannot read — malformed, never uploaded,
+ * expired, already consumed — is one condition on every driver
+ * ("unknown or expired"): a bucket cannot distinguish them, so neither
+ * does the wire.
+ *
+ * Proven by __tests__/staging.test.ts over a fake driver and over the
+ * real local driver with its slot registry; the conformance suite's
+ * transfer-lane block pins the wire behaviour on both editions.
+ */
+import { randomBytes } from "node:crypto";
+import { ArtifactStorageNotFoundError } from "../../../artifactstorage/artifact-storage.js";
+import { DEFAULT_SLOT_TTL_MS, DOWNLOAD_URL_TTL_MS, MAX_ZIP_SIZE, REF_BYTE_LEN, REF_PREFIX, STAGING_KEY_PREFIX, } from "../constants.js";
+import { SlotUnknownError } from "./slots.js";
+/** The hex the reference and the staging key share; 128 bits, lowercase. */
+const HEX = new RegExp(`^[0-9a-f]{${REF_BYTE_LEN * 2}}$`);
+const STAGED_ARCHIVE_SUFFIX = ".zip";
+/** The shared hex of a well-formed reference or key, else undefined. */
+function hexBetween(value, prefix, suffix) {
+    if (!value.startsWith(prefix) || !value.endsWith(suffix)) {
+        return undefined;
+    }
+    const hex = value.slice(prefix.length, value.length - suffix.length);
+    return HEX.test(hex) ? hex : undefined;
+}
+/** A fresh upload reference: the prefix and 128 random bits, hex. */
+export function newUploadRef() {
+    return REF_PREFIX + randomBytes(REF_BYTE_LEN).toString("hex");
+}
+/**
+ * The staging key a reference's bytes land under, or undefined when the
+ * reference is not one this server could have minted. Refs arrive from
+ * clients (the push request, the lane's URL path), so the shape is
+ * checked before it becomes a storage key.
+ */
+export function stagingKeyOf(ref) {
+    const hex = hexBetween(ref, REF_PREFIX, "");
+    return hex === undefined
+        ? undefined
+        : `${STAGING_KEY_PREFIX}${hex}${STAGED_ARCHIVE_SUFFIX}`;
+}
+/**
+ * The reference for a staging key this module minted. Keys reach here from
+ * the domain's own mint, never from a client, so a foreign shape is a
+ * programming error and throws.
+ */
+export function uploadRefOf(stagingKey) {
+    const hex = hexBetween(stagingKey, STAGING_KEY_PREFIX, STAGED_ARCHIVE_SUFFIX);
+    if (hex === undefined) {
+        throw new Error(`${stagingKey} is not a staging key this domain minted`);
+    }
+    return REF_PREFIX + hex;
+}
+export function newArchiveStaging(driver, logger) {
+    return {
+        async mint(declaredSizeBytes) {
+            // The controllers refuse over-limit declarations with the limit in
+            // the message before reaching here; this is the module's own
+            // invariant, so no driver is ever asked to stage more than the
+            // archive ceiling.
+            if (declaredSizeBytes <= 0 || declaredSizeBytes > MAX_ZIP_SIZE) {
+                throw new Error(`declared size ${declaredSizeBytes} outside (0, ${MAX_ZIP_SIZE}]`);
+            }
+            const ref = newUploadRef();
+            const key = stagingKeyOf(ref);
+            if (key === undefined) {
+                throw new Error(`minted reference ${ref} has no staging key`);
+            }
+            const presigned = await driver.presignPut(key, declaredSizeBytes, DEFAULT_SLOT_TTL_MS);
+            return { ref, url: presigned.url, ttlMs: presigned.ttlMs };
+        },
+        async consume(ref) {
+            const key = stagingKeyOf(ref);
+            if (key === undefined) {
+                throw new SlotUnknownError();
+            }
+            let data;
+            try {
+                // The allocation is bounded by construction: a bucket accepts only
+                // the signed Content-Length, the slot registry only the reserved
+                // size, and both were checked against MAX_ZIP_SIZE at mint.
+                data = await driver.download(key);
+            }
+            catch (error) {
+                if (error instanceof ArtifactStorageNotFoundError) {
+                    throw new SlotUnknownError();
+                }
+                throw error;
+            }
+            try {
+                await driver.delete(key);
+            }
+            catch (error) {
+                logger.error("failed to delete consumed staged artifact", {
+                    stagingKey: key,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return data;
+        },
+        async downloadUrl(storageKey) {
+            const url = await driver.getSignedUrl(storageKey, DOWNLOAD_URL_TTL_MS, "");
+            return { url, ttlMs: DOWNLOAD_URL_TTL_MS };
+        },
+    };
+}
+//# sourceMappingURL=staging.js.map

package/dist/domain/skill/transfer/staging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.js","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/staging.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/steps/resolve-artifact-source.d.ts

@@ -8,17 +8,20 @@
  * are indistinguishable past this point.
  *
  * Skills carried this step alone (the Go ResolveArtifactSource port);
- * plugins are pushed the same two ways over the same upload slots (one
- * upload surface, as boot/compose.ts wires it), so the step lives
- * here and each kind names its lane-absent sentence and the request
- * fields it reads.
+ * plugins are pushed the same two ways over the same staging port (one
+ * upload surface, as boot/compose.ts wires it), so the step lives here
+ * and each kind names its lane-absent sentence and the request fields it
+ * reads. The staging port (domain/skill/transfer/staging.ts) hides which
+ * blob driver holds the bytes: the step never sees a slot or a bucket.
  *
  * The unusable-reference arm is INVALID_ARGUMENT, not a server fault: an
- * unknown, expired, already consumed, or minted-but-never-uploaded
- * reference all mean the client must re-mint and re-upload.
+ * unknown, expired, already consumed, or never-uploaded reference all mean
+ * the client must re-mint and re-upload. Any other failure reading the
+ * staged bytes is the driver's — an infrastructure fault the executor
+ * answers as a sanitized Internal, never dressed as the client's mistake.
  */
 import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
-import type { UploadSlots } from "../../domain/skill/transfer/slots.js";
+import type { ArchiveStaging } from "../../domain/skill/transfer/staging.js";
 import type { PipelineStep } from "../pipeline.js";
 /** Where the resolved bytes ride for every downstream step. */
 export declare const ARTIFACT_BYTES_KEY = "pushArtifactBytes";
@@ -31,5 +34,5 @@ export interface ArtifactSourceBinding<Desc extends DescMessage> {
     /** The FailedPrecondition copy when no lane is configured; each kind pins its own. */
     readonly laneNotConfigured: string;
 }
-export declare function newResolveArtifactSourceStep<Desc extends DescMessage>(slots: UploadSlots | undefined, binding: ArtifactSourceBinding<Desc>): PipelineStep<Desc>;
+export declare function newResolveArtifactSourceStep<Desc extends DescMessage>(staging: ArchiveStaging | undefined, binding: ArtifactSourceBinding<Desc>): PipelineStep<Desc>;
 //# sourceMappingURL=resolve-artifact-source.d.ts.map

package/dist/pipeline/steps/resolve-artifact-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-artifact-source.d.ts","sourceRoot":"","sources":["../../../src/pipeline/steps/resolve-artifact-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,WAAW;IAC7D,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG;QACjC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;KACpC,CAAC;IACF,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,wBAAgB,4BAA4B,CAAC,IAAI,SAAS,WAAW,EACnE,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,qBAAqB,CAAC,IAAI,CAAC,GACnC,YAAY,CAAC,IAAI,CAAC,CAuBpB"}
+{"version":3,"file":"resolve-artifact-source.d.ts","sourceRoot":"","sources":["../../../src/pipeline/steps/resolve-artifact-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAE7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,WAAW;IAC7D,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG;QACjC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;KACpC,CAAC;IACF,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,wBAAgB,4BAA4B,CAAC,IAAI,SAAS,WAAW,EACnE,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,OAAO,EAAE,qBAAqB,CAAC,IAAI,CAAC,GACnC,YAAY,CAAC,IAAI,CAAC,CA0BpB"}