@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/README.md

@@ -15,7 +15,7 @@ citations are the port's provenance record.
 
 ## Contract promise
 
-The wire contract is shared: the cloud Java service, the runner, every
+The wire contract is shared: the cloud composition, the runner, every
 published SDK, and databases written before the cutover all speak it.
 Byte-pinned identifiers, error copy, and streaming behavior are contract —
 every deliberate exception is recorded in the program's parity-deltas
@@ -89,5 +89,5 @@ npm run build:slim && npm run verify:slim
 
 Or from the repo root: `make build-server`, `make test-server`.
 
-Coding standards for this service live in
-`.cursor/rules/backend/ts-server-guidelines.mdc`.
+The binding laws and read-order for this service are in [`AGENTS.md`](AGENTS.md)
+beside this file; repo-wide laws are in the root `AGENTS.md`.

package/dist/archive/content-store.d.ts

@@ -0,0 +1,35 @@
+import type { ArtifactStorage } from "../artifactstorage/artifact-storage.js";
+/**
+ * Storage abstraction for content-addressed archives. The interface exists
+ * for the same reason Go's did: the cloud edition uses R2 behind the
+ * identical surface, and a controller must not know which one it holds.
+ */
+export interface ContentAddressedArchiveStore {
+    /** Saves an archive under its content hash; returns the storage key. */
+    store(hash: string, data: Uint8Array): Promise<string>;
+    /** Loads an archive by storage key; throws ArtifactNotFoundError if absent. */
+    get(storageKey: string): Promise<Uint8Array>;
+    /** Whether an archive with this content hash already exists (dedupe). */
+    exists(hash: string): Promise<boolean>;
+    /** The storage key for a hash, without storing ("<prefix><hash>.zip"). */
+    getStorageKey(hash: string): string;
+    /** The stored archive's byte size via stat — never loads content. */
+    size(storageKey: string): Promise<number>;
+}
+/**
+ * A storage key that addresses nothing inside the store — missing file OR
+ * a traversal-shaped key (both render as Go's "artifact not found: %s").
+ */
+export declare class ArtifactNotFoundError extends Error {
+    constructor(storageKey: string);
+}
+/**
+ * The store over a blob driver. Object-literal factory rather than a class:
+ * all state is the captured driver and prefix, and the seam-adapter shape
+ * matches runner-credential-provider.ts (the house style for ports).
+ *
+ * `keyPrefix` ends with a slash (`skills/`); it is also the download lane's
+ * containment prefix, so the two agree by construction.
+ */
+export declare function newContentAddressedArchiveStore(driver: ArtifactStorage, keyPrefix: string): ContentAddressedArchiveStore;
+//# sourceMappingURL=content-store.d.ts.map

package/dist/archive/content-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-store.d.ts","sourceRoot":"","sources":["../../src/archive/content-store.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAG9E;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wEAAwE;IACxE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,+EAA+E;IAC/E,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,yEAAyE;IACzE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,0EAA0E;IAC1E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,qEAAqE;IACrE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,UAAU,EAAE,MAAM;CAI/B;AAKD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,GAChB,4BAA4B,CAwD9B"}

package/dist/archive/content-store.js

@@ -0,0 +1,98 @@
+/**
+ * The content-addressed archive store — a domain port over the one
+ * ArtifactStorage blob driver: keys are `<prefix><sha256>.zip`, writes are
+ * once and never garbage-collected (historical versions stay downloadable
+ * through the keys a version history exposes), and a key that addresses
+ * nothing inside the store collapses to one not-found before the driver
+ * sees it. Skills shipped this shape first
+ * (pkg/domain/skill/storage/artifact_storage.go, then the TS port under
+ * domain/skill/storage); plugins need the identical port under another
+ * prefix, so the implementation lives here and each domain names its
+ * instance (`skills/`, `plugins/`).
+ *
+ * Why the traversal guard is the port's, not the driver's: a
+ * client-supplied storage key that resolves outside the store must read
+ * exactly like a missing file — the driver's own containment refusal is a
+ * distinguishable error, and distinguishing them would tell a probing
+ * caller which escapes exist. Lexical, against a fixed virtual root, so
+ * the judgment is identical on every backend.
+ *
+ * Key shape: a LITERAL forward-slash join, never path.join — the key is a
+ * wire-visible identifier (status.artifact_storage_key, download URLs, the
+ * lane's prefix check) and Windows support arrives only through this server
+ * (#24); path.join would mint backslash keys there.
+ *
+ * Proven by the skill store's __tests__/artifact-storage.test.ts (the
+ * `skills/` instance) and by __tests__/content-store.test.ts.
+ */
+import path from "node:path";
+import { ArtifactStorageNotFoundError } from "../artifactstorage/artifact-storage.js";
+/**
+ * A storage key that addresses nothing inside the store — missing file OR
+ * a traversal-shaped key (both render as Go's "artifact not found: %s").
+ */
+export class ArtifactNotFoundError extends Error {
+    constructor(storageKey) {
+        super(`artifact not found: ${storageKey}`);
+        this.name = "ArtifactNotFoundError";
+    }
+}
+/** Archives are zip files; the driver stores the honest type. */
+const ARCHIVE_CONTENT_TYPE = "application/zip";
+/**
+ * The store over a blob driver. Object-literal factory rather than a class:
+ * all state is the captured driver and prefix, and the seam-adapter shape
+ * matches runner-credential-provider.ts (the house style for ports).
+ *
+ * `keyPrefix` ends with a slash (`skills/`); it is also the download lane's
+ * containment prefix, so the two agree by construction.
+ */
+export function newContentAddressedArchiveStore(driver, keyPrefix) {
+    const virtualRoot = path.resolve(path.sep, "archive-store");
+    const keyEscapesStore = (storageKey) => {
+        const resolved = path.resolve(virtualRoot, storageKey);
+        return (resolved !== virtualRoot && !resolved.startsWith(virtualRoot + path.sep));
+    };
+    return {
+        getStorageKey(hash) {
+            return `${keyPrefix}${hash}.zip`;
+        },
+        async store(hash, data) {
+            const storageKey = this.getStorageKey(hash);
+            await driver.upload(storageKey, data, ARCHIVE_CONTENT_TYPE);
+            return storageKey;
+        },
+        async get(storageKey) {
+            if (keyEscapesStore(storageKey)) {
+                throw new ArtifactNotFoundError(storageKey);
+            }
+            try {
+                return await driver.download(storageKey);
+            }
+            catch (error) {
+                if (error instanceof ArtifactStorageNotFoundError) {
+                    throw new ArtifactNotFoundError(storageKey);
+                }
+                throw new Error(`failed to read artifact: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        async exists(hash) {
+            return driver.exists(this.getStorageKey(hash));
+        },
+        async size(storageKey) {
+            if (keyEscapesStore(storageKey)) {
+                throw new ArtifactNotFoundError(storageKey);
+            }
+            try {
+                return await driver.size(storageKey);
+            }
+            catch (error) {
+                if (error instanceof ArtifactStorageNotFoundError) {
+                    throw new ArtifactNotFoundError(storageKey);
+                }
+                throw new Error(`failed to stat artifact: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=content-store.js.map

package/dist/archive/content-store.js.map

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

package/dist/archive/inflate.d.ts

@@ -0,0 +1,22 @@
+import type { ZipStructuralEntry } from "@stigmer/zip-structure";
+export type InflateFailureKind = 
+/** The inflated output passed `maxSize`. */
+"too-large"
+/** zlib refused the payload; `detail` carries its message. */
+ | "read-failed"
+/** A compression method neither Go nor this gate registers. */
+ | "unsupported-method"
+/** The inflated bytes do not match the entry's CRC. */
+ | "checksum";
+/** A typed refusal; the kind that called maps it to its pinned sentence. */
+export declare class InflateError extends Error {
+    readonly kind: InflateFailureKind;
+    readonly detail: string;
+    constructor(kind: InflateFailureKind, detail: string);
+}
+/**
+ * Inflates one entry to at most `maxSize` bytes and verifies its CRC.
+ * The cap bounds the actual output, not the declaration.
+ */
+export declare function inflateEntry(entry: ZipStructuralEntry, maxSize: number): Uint8Array;
+//# sourceMappingURL=inflate.d.ts.map

package/dist/archive/inflate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inflate.d.ts","sourceRoot":"","sources":["../../src/archive/inflate.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAMjE,MAAM,MAAM,kBAAkB;AAC5B,4CAA4C;AAC1C,WAAW;AACb,8DAA8D;GAC5D,aAAa;AACf,+DAA+D;GAC7D,oBAAoB;AACtB,uDAAuD;GACrD,UAAU,CAAC;AAEf,4EAA4E;AAC5E,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,IAAI,EAAE,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,MAAM;CAK1B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,GACd,UAAU,CA6CZ"}

package/dist/archive/inflate.js

@@ -0,0 +1,75 @@
+/**
+ * Reading one archive entry under a real cap. Declared sizes are client
+ * claims, so every gate that opens an entry bounds the ACTUAL inflated
+ * output (`maxOutputLength`), verifies the CRC the way Go's checksumReader
+ * does on every read, and opens only the two methods the platform
+ * registers (stored, deflated). The skill gate did this for SKILL.md alone;
+ * a plugin reads many documents through the same discipline, so the read
+ * lives here and each kind keeps its own sentences: the outcome is a typed
+ * failure, never prose, because the skill's copy is byte-pinned wire
+ * contract and a plugin's names a different document.
+ *
+ * Proven by __tests__/inflate.test.ts and, through composition, by the
+ * skill gate's zip-gate.test.ts.
+ */
+import { inflateRawSync } from "node:zlib";
+import { crc32 } from "@stigmer/zip-structure";
+/** ZIP compression methods the gate can open (Go registers the same two). */
+const METHOD_STORED = 0;
+const METHOD_DEFLATED = 8;
+/** A typed refusal; the kind that called maps it to its pinned sentence. */
+export class InflateError extends Error {
+    kind;
+    detail;
+    constructor(kind, detail) {
+        super(`${kind}: ${detail}`);
+        this.kind = kind;
+        this.detail = detail;
+        this.name = "InflateError";
+    }
+}
+/**
+ * Inflates one entry to at most `maxSize` bytes and verifies its CRC.
+ * The cap bounds the actual output, not the declaration.
+ */
+export function inflateEntry(entry, maxSize) {
+    let content;
+    switch (entry.compressionMethod) {
+        case METHOD_STORED:
+            content = entry.compressedData;
+            break;
+        case METHOD_DEFLATED:
+            try {
+                content = new Uint8Array(inflateRawSync(entry.compressedData, {
+                    maxOutputLength: maxSize + 1,
+                }));
+            }
+            catch (error) {
+                if (isOutputLengthError(error)) {
+                    throw new InflateError("too-large", `output exceeds ${maxSize} bytes`);
+                }
+                throw new InflateError("read-failed", error instanceof Error ? error.message : String(error));
+            }
+            break;
+        default:
+            // Go: File.Open returns ErrAlgorithm for methods without a registered
+            // decompressor; each kind pins the text via its own %w-shaped arm.
+            throw new InflateError("unsupported-method", "zip: unsupported compression algorithm");
+    }
+    if (content.length > maxSize) {
+        throw new InflateError("too-large", `output exceeds ${maxSize} bytes`);
+    }
+    if (crc32(content) !== entry.crc32) {
+        // Go's checksumReader: stdlib ErrChecksum via the read-error arm.
+        throw new InflateError("checksum", "zip: checksum error");
+    }
+    return content;
+}
+/** node:zlib's maxOutputLength violation (the output-cap arm). */
+function isOutputLengthError(error) {
+    return (error instanceof Error &&
+        (("code" in error &&
+            error.code === "ERR_BUFFER_TOO_LARGE") ||
+            error.message.includes("maxOutputLength")));
+}
+//# sourceMappingURL=inflate.js.map

package/dist/archive/inflate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inflate.js","sourceRoot":"","sources":["../../src/archive/inflate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAG/C,6EAA6E;AAC7E,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,eAAe,GAAG,CAAC,CAAC;AAY1B,4EAA4E;AAC5E,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE1B;IACA;IAFX,YACW,IAAwB,EACxB,MAAc;QAEvB,KAAK,CAAC,GAAG,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAHnB,SAAI,GAAJ,IAAI,CAAoB;QACxB,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAyB,EACzB,OAAe;IAEf,IAAI,OAAmB,CAAC;IACxB,QAAQ,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAChC,KAAK,aAAa;YAChB,OAAO,GAAG,KAAK,CAAC,cAAc,CAAC;YAC/B,MAAM;QACR,KAAK,eAAe;YAClB,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,UAAU,CACtB,cAAc,CAAC,KAAK,CAAC,cAAc,EAAE;oBACnC,eAAe,EAAE,OAAO,GAAG,CAAC;iBAC7B,CAAC,CACH,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC/B,MAAM,IAAI,YAAY,CACpB,WAAW,EACX,kBAAkB,OAAO,QAAQ,CAClC,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,YAAY,CACpB,aAAa,EACb,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;YACJ,CAAC;YACD,MAAM;QACR;YACE,sEAAsE;YACtE,mEAAmE;YACnE,MAAM,IAAI,YAAY,CACpB,oBAAoB,EACpB,wCAAwC,CACzC,CAAC;IACN,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,kBAAkB,OAAO,QAAQ,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC;QACnC,kEAAkE;QAClE,MAAM,IAAI,YAAY,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kEAAkE;AAClE,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,CAAC,CAAC,MAAM,IAAI,KAAK;YACd,KAA2B,CAAC,IAAI,KAAK,sBAAsB,CAAC;YAC7D,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAC7C,CAAC;AACJ,CAAC"}

package/dist/archive/limits.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The platform's archive limits — one home for every ZIP-bomb budget the
+ * server applies to a pushed archive, whichever kind it becomes. Skills
+ * carried these alone until plugins arrived (also pushed as a ZIP); the
+ * values stay byte-pinned to the retired Go gate's (pkg/domain/skill/storage/
+ * zip_extractor.go), because every sentence quoting them is wire contract
+ * and the transfer lane refuses over-limit declarations by them before a
+ * byte moves.
+ *
+ * A per-kind cap that is NOT an archive budget (the 1 MB SKILL.md
+ * extraction cap) stays with its kind: it bounds one document, not the
+ * archive.
+ */
+/**
+ * The compressed-archive ceiling. The platform's artifact size limit, not
+ * just an extraction guard: createArtifactUploadUrl enforces it before any
+ * bytes move and clients quote it in fail-loud size errors (#675).
+ */
+export declare const MAX_ZIP_SIZE: number;
+/** Total declared-uncompressed budget across all entries (ZIP-bomb guard). */
+export declare const MAX_UNCOMPRESSED_SIZE: number;
+/** Per-file declared compression ratio ceiling (ZIP-bomb guard). */
+export declare const MAX_COMPRESSION_RATIO = 100;
+/** Entry-count ceiling. */
+export declare const MAX_FILES = 10000;
+/** The budgets `validateArchiveStructure` applies; the platform's by default. */
+export interface ArchiveLimits {
+    readonly maxFiles: number;
+    readonly maxUncompressedSize: number;
+    readonly maxCompressionRatio: number;
+}
+export declare const PLATFORM_ARCHIVE_LIMITS: ArchiveLimits;
+//# sourceMappingURL=limits.d.ts.map

package/dist/archive/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/archive/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAoB,CAAC;AAE9C,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AAEvD,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,2BAA2B;AAC3B,eAAO,MAAM,SAAS,QAAS,CAAC;AAEhC,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,uBAAuB,EAAE,aAIrC,CAAC"}

package/dist/archive/limits.js

@@ -0,0 +1,31 @@
+/**
+ * The platform's archive limits — one home for every ZIP-bomb budget the
+ * server applies to a pushed archive, whichever kind it becomes. Skills
+ * carried these alone until plugins arrived (also pushed as a ZIP); the
+ * values stay byte-pinned to the retired Go gate's (pkg/domain/skill/storage/
+ * zip_extractor.go), because every sentence quoting them is wire contract
+ * and the transfer lane refuses over-limit declarations by them before a
+ * byte moves.
+ *
+ * A per-kind cap that is NOT an archive budget (the 1 MB SKILL.md
+ * extraction cap) stays with its kind: it bounds one document, not the
+ * archive.
+ */
+/**
+ * The compressed-archive ceiling. The platform's artifact size limit, not
+ * just an extraction guard: createArtifactUploadUrl enforces it before any
+ * bytes move and clients quote it in fail-loud size errors (#675).
+ */
+export const MAX_ZIP_SIZE = 100 * 1024 * 1024;
+/** Total declared-uncompressed budget across all entries (ZIP-bomb guard). */
+export const MAX_UNCOMPRESSED_SIZE = 500 * 1024 * 1024;
+/** Per-file declared compression ratio ceiling (ZIP-bomb guard). */
+export const MAX_COMPRESSION_RATIO = 100;
+/** Entry-count ceiling. */
+export const MAX_FILES = 10_000;
+export const PLATFORM_ARCHIVE_LIMITS = {
+    maxFiles: MAX_FILES,
+    maxUncompressedSize: MAX_UNCOMPRESSED_SIZE,
+    maxCompressionRatio: MAX_COMPRESSION_RATIO,
+};
+//# sourceMappingURL=limits.js.map

package/dist/archive/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/archive/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvD,oEAAoE;AACpE,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,2BAA2B;AAC3B,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AAShC,MAAM,CAAC,MAAM,uBAAuB,GAAkB;IACpD,QAAQ,EAAE,SAAS;IACnB,mBAAmB,EAAE,qBAAqB;IAC1C,mBAAmB,EAAE,qBAAqB;CAC3C,CAAC"}

package/dist/archive/open.d.ts

@@ -0,0 +1,24 @@
+import type { ArchiveLimits } from "./limits.js";
+import type { PrefilteredEntry } from "./prefilter.js";
+/** A parsed, pre-filtered archive with its content-addressed identity. */
+export interface OpenedArchive {
+    /** SHA-256 hex of the archive bytes. */
+    readonly hash: string;
+    /** The entries a kind may read, names sanitised, shadows dropped. */
+    readonly entries: readonly PrefilteredEntry[];
+}
+/**
+ * Bounds, hashes, parses and pre-filters. Throws plain Errors with
+ * byte-pinned messages; the caller owns the gRPC code.
+ */
+export declare function openArchive(bytes: Uint8Array, maxZipSize?: number): OpenedArchive;
+/**
+ * The structural walk: empty archive, file-count cap, then per entry the
+ * control-character rule, the running declared-uncompressed budget
+ * (fail-fast) and the per-file compression-ratio cap. `onEntry` sees each
+ * sanitised name in order so a kind can track its own requirements.
+ */
+export declare function validateArchiveStructure(entries: readonly PrefilteredEntry[], limits: ArchiveLimits, onEntry?: (name: string) => void): void;
+/** SHA-256 hex of the archive bytes (Go CalculateHash). */
+export declare function calculateHash(data: Uint8Array): string;
+//# sourceMappingURL=open.d.ts.map

package/dist/archive/open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../src/archive/open.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,UAAU,GAAE,MAAqB,GAChC,aAAa,CAsBf;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC/B,IAAI,CA2CN;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEtD"}

package/dist/archive/open.js

@@ -0,0 +1,93 @@
+/**
+ * Opening a pushed archive — the kind-agnostic half of the ZIP gate every
+ * archive-shaped push runs (skills, plugins). Two steps, both pure over the
+ * bytes: `openArchive` bounds the compressed size, hashes the bytes (the
+ * content-addressed version identity), parses the central directory and
+ * applies the safearchive prefilter; `validateArchiveStructure` walks the
+ * pre-filtered entries in the retired Go gate's exact order (empty
+ * archive, file count, then per entry the filename control-character rule,
+ * the running declared-uncompressed budget and the per-file ratio cap).
+ *
+ * What a KIND requires of the entries (a root SKILL.md, a plugin manifest)
+ * is not here: the walk accepts an `onEntry` observer so a kind tracks what
+ * it needs in the same pass and rules on it afterwards, which keeps the
+ * observable error order the skill gate's tests pin.
+ *
+ * Error text is wire-visible contract: the sentences below are the Go
+ * gate's verbatim, wrapped by each kind's push step into its own
+ * InvalidArgument arm. Only declared sizes are judged here; inflating an
+ * entry under a real cap is `inflate.ts`'s job.
+ *
+ * Proven by the skill gate's __tests__/zip-gate.test.ts (which composes
+ * these) and by __tests__/open.test.ts for the plugin-shaped path.
+ */
+import { createHash } from "node:crypto";
+import { parseZipStructure } from "@stigmer/zip-structure";
+import { MAX_ZIP_SIZE } from "./limits.js";
+import { applyEntryPrefilter } from "./prefilter.js";
+/**
+ * Bounds, hashes, parses and pre-filters. Throws plain Errors with
+ * byte-pinned messages; the caller owns the gRPC code.
+ */
+export function openArchive(bytes, maxZipSize = MAX_ZIP_SIZE) {
+    if (bytes.length > maxZipSize) {
+        throw new Error(`ZIP file too large: ${bytes.length} bytes (max: ${maxZipSize})`);
+    }
+    const hash = calculateHash(bytes);
+    let entries;
+    try {
+        entries = parseZipStructure(bytes);
+    }
+    catch {
+        // Go's zip.NewReader surfaces stdlib ErrFormat here; its text is what
+        // clients see via the %w chain, so it is pinned verbatim.
+        throw new Error("invalid ZIP file: zip: not a valid zip file");
+    }
+    // safearchive MaximumSecurityMode rewrites the entry list before any
+    // validation sees it — sanitized names, shadowed/special/8.3 entries
+    // dropped.
+    return { hash, entries: applyEntryPrefilter(entries) };
+}
+/**
+ * The structural walk: empty archive, file-count cap, then per entry the
+ * control-character rule, the running declared-uncompressed budget
+ * (fail-fast) and the per-file compression-ratio cap. `onEntry` sees each
+ * sanitised name in order so a kind can track its own requirements.
+ */
+export function validateArchiveStructure(entries, limits, onEntry) {
+    if (entries.length === 0) {
+        throw new Error("ZIP file is empty");
+    }
+    if (entries.length > limits.maxFiles) {
+        throw new Error(`too many files in ZIP: ${entries.length} (max: ${limits.maxFiles})`);
+    }
+    let totalUncompressedSize = 0;
+    for (const { name, entry } of entries) {
+        onEntry?.(name);
+        // Reject null bytes and control characters in entry names (code
+        // points, not UTF-16 units — Go ranges over runes).
+        for (const ch of name) {
+            const codePoint = ch.codePointAt(0);
+            if (codePoint < 32 || codePoint === 127) {
+                throw new Error(`invalid character in filename: ${name}`);
+            }
+        }
+        // Track the declared uncompressed total (fail fast once exceeded).
+        totalUncompressedSize += entry.uncompressedSize;
+        if (totalUncompressedSize > limits.maxUncompressedSize) {
+            throw new Error(`total uncompressed size too large: ${totalUncompressedSize} bytes (max: ${limits.maxUncompressedSize})`);
+        }
+        // Per-file compression ratio (ZIP-bomb guard); integer division as Go.
+        if (entry.compressedSize > 0) {
+            const ratio = Math.floor(entry.uncompressedSize / entry.compressedSize);
+            if (ratio > limits.maxCompressionRatio) {
+                throw new Error(`suspicious compression ratio in ${name}: ${ratio}:1 (max: ${limits.maxCompressionRatio}:1)`);
+            }
+        }
+    }
+}
+/** SHA-256 hex of the archive bytes (Go CalculateHash). */
+export function calculateHash(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+//# sourceMappingURL=open.js.map

package/dist/archive/open.js.map

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

package/dist/{domain/skill/storage → archive}/prefilter.d.ts

@@ -28,6 +28,11 @@
  * bits; FAT/NTFS/VFAT creators carry MSDOS bits that can never encode a
  * symlink or special file; unknown creators decode to a regular file.
  *
+ * Shared by every archive gate the server runs (skills, plugins): the
+ * filter describes what an archive IS before any kind reads it, so it
+ * lives with the archive plumbing rather than with the first kind that
+ * needed it.
+ *
  * Proven by __tests__/prefilter.test.ts (byte-crafted fixtures per DD-001).
  */
 import type { ZipStructuralEntry } from "@stigmer/zip-structure";

package/dist/archive/prefilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefilter.d.ts","sourceRoot":"","sources":["../../src/archive/prefilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAIjE;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUlD;AA2BD,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK/D;AAgBD,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAetE;AAID;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,gBAAgB,EAAE,CAwCpB"}

package/dist/archive/prefilter.js.map

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

package/dist/archive/write.d.ts

@@ -0,0 +1,8 @@
+/** One file to write: a plugin-relative POSIX path and its bytes. */
+export interface ArchiveFile {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+/** Writes `files` as one deflated archive whose bytes depend on the files alone. */
+export declare function writeArchive(files: ReadonlyArray<ArchiveFile>): Uint8Array;
+//# sourceMappingURL=write.d.ts.map

package/dist/archive/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/archive/write.ts"],"names":[],"mappings":"AAoBA,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAaD,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,UAAU,CAe1E"}

package/dist/archive/write.js

@@ -0,0 +1,44 @@
+/**
+ * Writing a deterministic archive. The server writes ZIPs for one reason: a
+ * plugin's skills are pushed through the skill pipeline as archives of
+ * their own, and a skill's version IS the SHA-256 of its archive bytes, so
+ * the same files must always produce the same bytes or every re-install
+ * would mint a new skill version out of nothing. Determinism comes from
+ * three choices, each mirrored from the CLI's skill packager
+ * (client-apps/cli/src/resources/skill.ts): entries sorted by path, one
+ * fixed DOS-epoch mtime on every entry (fflate would otherwise stamp the
+ * wall clock), and one fixed deflate level.
+ *
+ * fflate is the ratified server dependency for ZIP work (see
+ * domain/agentexecution/artifacts.ts); this module is its one write site.
+ *
+ * Proven by __tests__/write.test.ts: two writes of the same files are
+ * byte-equal, entry order does not matter, and the result round-trips
+ * through the server's own reader.
+ */
+import { zipSync } from "fflate";
+/**
+ * fflate stamps the archive's creation time into every entry when no mtime
+ * is given; pinning the DOS epoch removes the one source of byte-level
+ * variance. Local-field construction is deliberate: DOS timestamps are
+ * local time, and this instant is representable in every zone.
+ */
+const DETERMINISTIC_ZIP_MTIME = new Date(1980, 0, 1);
+/** The CLI's level; changing it would move every digest in the field. */
+const DEFLATE_LEVEL = 6;
+/** Writes `files` as one deflated archive whose bytes depend on the files alone. */
+export function writeArchive(files) {
+    const sorted = [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const tree = {};
+    for (const file of sorted) {
+        if (file.path in tree) {
+            throw new Error(`archive path '${file.path}' listed twice`);
+        }
+        tree[file.path] = file.bytes;
+    }
+    return zipSync(tree, {
+        level: DEFLATE_LEVEL,
+        mtime: DETERMINISTIC_ZIP_MTIME,
+    });
+}
+//# sourceMappingURL=write.js.map

package/dist/archive/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/archive/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAQjC;;;;;GAKG;AACH,MAAM,uBAAuB,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAErD,yEAAyE;AACzE,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,KAAiC;IAC5D,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACtC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC/C,CAAC;IACF,MAAM,IAAI,GAA+B,EAAE,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,CAAC,IAAI,gBAAgB,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IAC/B,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,EAAE;QACnB,KAAK,EAAE,aAAa;QACpB,KAAK,EAAE,uBAAuB;KAC/B,CAAC,CAAC;AACL,CAAC"}