@mcsherrylabs/evolver-mcp 0.12.0 → 0.14.0

package/dist/content-files.js

@@ -0,0 +1,79 @@
+// File-backed content is an explicit host-filesystem capability, never a model-context blob.
+// The SDK still owns HTTP and streaming transport. The file layer owns byte bounds, incremental
+// hashing and atomic output; neither this module nor the tools implement the node protocol.
+import { parseAccess, OPEN_NOTE, RESTRICTED_NOTE } from "@mcsherrylabs/evolver-core";
+import { ContentHttpError } from "@mcsherrylabs/evolver-client";
+import { FileAccessError, fileName } from "./files.js";
+/** Deliberately do not echo exceptions/response text/host paths: a server can reflect content,
+ * and some TLS errors include certificate details. A completed HTTP refusal is not transport loss. */
+export function contentFileFailure(e, url, operation) {
+    const aftermath = operation === "publish" ? "upload storage is unconfirmed" : "no completed output metadata returned";
+    if (e instanceof FileAccessError && e.code === "publication_unknown")
+        return { kind: "partial", what: operation, cause: "file_publication_unknown; target may exist or have been visible; this is NOT a no-write refusal. Do not retry or automatically delete the final target; operator inspection is required." +
+                (e.cleanupWarning ? " staging_cleanup_failed; protected staging may also remain." : "") };
+    if (e instanceof FileAccessError && e.code !== "transfer_failed")
+        return { kind: "partial", what: operation, cause: `file_${e.code}; ${aftermath}` +
+                (e.cleanupWarning ? "; staging_cleanup_failed; operator inspection of protected staging may be required" : "") };
+    if (e instanceof Error && e.name === "AbortError")
+        return { kind: "partial", what: operation, cause: `cancelled; ${aftermath}` };
+    const message = e instanceof Error ? e.message : "";
+    const status = e instanceof ContentHttpError ? String(e.status) :
+        /^(?:postContent(?:Stream)?|getContentStream): HTTP ([1-5][0-9]{2})\b/.exec(message)?.[1];
+    if (status)
+        return { kind: "partial", what: operation,
+            cause: `content_http_${status}; not complete, not retried or republished open; ${aftermath}` };
+    return { kind: "unreachable", chain: url, cause: `content_transfer_failed; ${aftermath}` +
+            (e instanceof FileAccessError && e.cleanupWarning ? "; staging_cleanup_failed; operator inspection of protected staging may be required" : "") };
+}
+export const contentFileDisabled = () => ({ kind: "misconfigured", what: "file content access is disabled",
+    fix: "operator must opt in with EVOLVER_FILE_ROOT (dedicated server-local0700 directory) and reload; client roots do not authorize host access" });
+export async function publishFile(deps, req, signal) {
+    // Share the INLINE ACL parser; do not trim/filter a malformed grant into open publication.
+    const access = parseAccess(req.access, req.authorizedPrincipals);
+    if ("kind" in access)
+        return access;
+    if (!deps)
+        return contentFileDisabled();
+    try {
+        const file = fileName(req.file);
+        return await deps.files.transfer(files => files.withInput(file, async (input) => {
+            const result = await deps.client.postContentStream(input.stream, { size: input.size, signal: files.signal,
+                ...(access.mode === "restricted" ? { authorizedPrincipals: access.principals } : {}) });
+            const metadata = input.metadata();
+            if (result.size !== metadata.size || !/^[0-9a-f]{64}$/.test(result.key))
+                throw new FileAccessError("incomplete");
+            return { kind: "ok", value: { ...metadata, key: result.key, access: access.mode,
+                    ...(access.mode === "restricted" ? { authorizedPrincipals: access.principals } : {}),
+                    note: access.mode === "restricted" ? RESTRICTED_NOTE : OPEN_NOTE } };
+        }), signal);
+    }
+    catch (e) {
+        return contentFileFailure(e, deps.contentUrl, "publish");
+    }
+}
+export async function fetchFile(deps, req, signal) {
+    if (!deps)
+        return contentFileDisabled();
+    if (typeof req.key !== "string" || !/^[0-9a-f]{64}$/.test(req.key))
+        return { kind: "partial", what: "key", cause: "a content key must be exactly64 lowercase hex characters" };
+    const key = req.key;
+    try {
+        const file = fileName(req.file);
+        return await deps.files.transfer(async (files) => {
+            const result = await deps.client.getContentStream(key, { signal: files.signal });
+            if (result === null)
+                return { kind: "ok", value: null };
+            // A full-file tool never silently treats a partial response as the complete object.
+            if (result.status !== 200 || result.range !== null) {
+                await result.stream.cancel().catch(() => undefined);
+                throw new FileAccessError("incomplete");
+            }
+            const metadata = await files.writeNew(file, result.stream, result.size);
+            return { kind: "ok", value: { ...metadata, key } };
+        }, signal);
+    }
+    catch (e) {
+        return contentFileFailure(e, deps.contentUrl, "download");
+    }
+}
+//# sourceMappingURL=content-files.js.map

package/dist/content-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-files.js","sourceRoot":"","sources":["../src/content-files.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,gGAAgG;AAChG,4FAA4F;AAC5F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AASvD;sGACsG;AACtG,MAAM,UAAU,kBAAkB,CAAC,CAAU,EAAE,GAAW,EAAE,SAA2C;IACrG,MAAM,SAAS,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,uCAAuC,CAAC;IACtH,IAAI,CAAC,YAAY,eAAe,IAAI,CAAC,CAAC,IAAI,KAAK,qBAAqB;QAClE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,0LAA0L;gBAC1O,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,6DAA6D,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC9F,IAAI,CAAC,YAAY,eAAe,IAAI,CAAC,CAAC,IAAI,KAAK,iBAAiB;QAC9D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,IAAI,KAAK,SAAS,EAAE;gBAC9E,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,oFAAoF,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACrH,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY;QAC/C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,SAAS,EAAE,EAAE,CAAC;IAChF,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,MAAM,MAAM,GAAG,CAAC,YAAY,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/D,sEAAsE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5F,IAAI,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS;YACnD,KAAK,EAAE,gBAAgB,MAAM,oDAAoD,SAAS,EAAE,EAAE,CAAC;IACjG,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,4BAA4B,SAAS,EAAE;YACtF,CAAC,CAAC,YAAY,eAAe,IAAI,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,oFAAoF,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACrJ,CAAC;AACD,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAsB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,iCAAiC;IAC3H,GAAG,EAAE,0IAA0I,EAAE,CAAC,CAAC;AAErJ,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAiC,EAAE,GAEpE,EAAE,MAAoB;IACrB,2FAA2F;IAC3F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACjE,IAAI,MAAM,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,mBAAmB,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC5E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM;gBACvG,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC1F,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;gBAAE,MAAM,IAAI,eAAe,CAAC,YAAY,CAAC,CAAC;YACjH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI;oBAC7E,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACpF,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;QACzE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,kBAAkB,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAiC,EAAE,GAElE,EAAE,MAAoB;IACrB,IAAI,CAAC,IAAI;QAAE,OAAO,mBAAmB,EAAE,CAAC;IACxC,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAChE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,0DAA0D,EAAE,CAAC;IAC7G,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAC,KAAK,EAAC,EAAE;YAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YACjF,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACxD,oFAAoF;YACpF,IAAI,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnD,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;gBACpD,MAAM,IAAI,eAAe,CAAC,YAAY,CAAC,CAAC;YAC1C,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACxE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAC;QACrD,CAAC,EAAE,MAAM,CAAC,CAAC;IACb,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,kBAAkB,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAAC,CAAC;AAC5E,CAAC"}

package/dist/content-ranges.d.ts

@@ -0,0 +1,41 @@
+import type { FileContentDeps } from "./content-files.js";
+import type { FileCleanupWarning } from "./files.js";
+import type { ToolResult } from "@mcsherrylabs/evolver-core";
+export interface ByteInterval {
+    readonly from: number;
+    readonly toInclusive: number;
+}
+export type FileRangeResult = {
+    readonly status: "range";
+    readonly key: string;
+    readonly file: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly hashScope: "served-range";
+    /** False refers to the ORIGINAL object, even if this interval happens to cover all of it. */
+    readonly complete: false;
+    readonly rangeComplete: true;
+    readonly fileComplete: true;
+    readonly requested: ByteInterval;
+    readonly served: ByteInterval & {
+        readonly totalSize: number;
+    };
+    readonly clipped: boolean;
+    readonly cleanupWarning?: FileCleanupWarning;
+} | {
+    readonly status: "unsatisfiable";
+    readonly key: string;
+    readonly requested: ByteInterval;
+    readonly totalSize: number | null;
+    readonly complete: false;
+    readonly rangeComplete: false;
+    readonly fileComplete: false;
+};
+export declare function byteInterval(from: unknown, toInclusive: unknown, maxBytes: number): ByteInterval | ToolResult<never>;
+export declare function fetchRangeFile(deps: FileContentDeps | undefined, req: {
+    key?: unknown;
+    file?: unknown;
+    from?: unknown;
+    toInclusive?: unknown;
+}, signal?: AbortSignal): Promise<ToolResult<FileRangeResult | null>>;
+//# sourceMappingURL=content-ranges.d.ts.map

package/dist/content-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-ranges.d.ts","sourceRoot":"","sources":["../src/content-ranges.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,MAAM,WAAW,YAAY;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AACrF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAC5F,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;CAC9C,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACzF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC;CACvF,CAAC;AAGF,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,CAOpH;AAWD,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,EAAE,GAAG,EAAE;IAC3E,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CACtE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAyCpE"}

package/dist/content-ranges.js

@@ -0,0 +1,75 @@
+// Inclusive range semantics sit above the SDK's truthful HTTP metadata and reuse #11's
+// exact-byte, atomic no-overwrite file boundary. No headers, HTTP request or wire encoder here.
+import { contentFileDisabled, contentFileFailure } from "./content-files.js";
+import { fileName } from "./files.js";
+const nat = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function byteInterval(from, toInclusive, maxBytes) {
+    if (!nat(from) || !nat(toInclusive) || from > toInclusive)
+        return { kind: "partial", what: "range", cause: "invalid_range; inclusive bounds must be non-negative safe integers with from <= toInclusive" };
+    const count = toInclusive - from + 1;
+    if (!Number.isSafeInteger(count) || count > maxBytes)
+        return { kind: "partial", what: "range", cause: `range_too_large; requested inclusive interval must fit the ${maxBytes}-byte file bound` };
+    return { from, toInclusive };
+}
+/** SDK0.22 prerequisite: structured416, never regex-inferred from a transport exception.
+ * Unknown total stays null; malformed metadata is not an unsatisfiable interval result. */
+function unsatisfiable(e) {
+    if (!(e instanceof Error) || e.name !== "ContentRangeError")
+        return undefined;
+    const value = e;
+    if (value.status !== 416 || (value.totalSize !== null && !nat(value.totalSize)))
+        return undefined;
+    return { totalSize: value.totalSize };
+}
+export async function fetchRangeFile(deps, req, signal) {
+    if (!deps)
+        return contentFileDisabled();
+    if (typeof req.key !== "string" || !/^[0-9a-f]{64}$/.test(req.key))
+        return { kind: "partial", what: "key", cause: "a content key must be exactly 64 lowercase hex characters" };
+    const key = req.key;
+    const requested = byteInterval(req.from, req.toInclusive, deps.files.maxBytes);
+    if ("kind" in requested)
+        return requested;
+    try {
+        const file = fileName(req.file);
+        return await deps.files.transfer(async (files) => {
+            let result;
+            try {
+                result = await deps.client.getContentStream(key, { range: requested, signal: files.signal });
+            }
+            catch (e) {
+                const refusal = unsatisfiable(e);
+                if (!refusal)
+                    throw e;
+                return { kind: "ok", value: { status: "unsatisfiable", key, requested, totalSize: refusal.totalSize,
+                        complete: false, rangeComplete: false, fileComplete: false } };
+            }
+            if (result === null)
+                return { kind: "ok", value: null };
+            if (result.status === 200) {
+                await result.stream.cancel().catch(() => undefined);
+                return { kind: "partial", what: "range", cause: "range_ignored; server returned a full object, discarded without writing or retry" };
+            }
+            const served = result.range;
+            // The SDK validates headers. Also refuse a collaborator lacking/corrupting that contract;
+            // a stream alone can never prove the node honored the requested range.
+            if (result.status !== 206 || !served || !nat(served.from) || !nat(served.toInclusive) ||
+                !nat(served.totalSize) || served.from > served.toInclusive || served.toInclusive >= served.totalSize ||
+                served.from !== requested.from || served.toInclusive !== Math.min(requested.toInclusive, served.totalSize - 1) ||
+                !nat(result.size) || result.size !== served.toInclusive - served.from + 1) {
+                await result.stream.cancel().catch(() => undefined);
+                return { kind: "partial", what: "range", cause: "range_metadata_invalid; validated SDK206/served interval/total/byte-count metadata is required; no output" };
+            }
+            const metadata = await files.writeNew(file, result.stream, result.size);
+            return { kind: "ok", value: { status: "range", key, file: metadata.file, size: metadata.size,
+                    sha256: metadata.sha256, hashScope: "served-range", complete: false, rangeComplete: true, fileComplete: true,
+                    requested, served: { from: served.from, toInclusive: served.toInclusive, totalSize: served.totalSize },
+                    clipped: served.toInclusive !== requested.toInclusive,
+                    ...(metadata.cleanupWarning ? { cleanupWarning: metadata.cleanupWarning } : {}) } };
+        }, signal);
+    }
+    catch (e) {
+        return contentFileFailure(e, deps.contentUrl, "range");
+    }
+}
+//# sourceMappingURL=content-ranges.js.map

package/dist/content-ranges.js.map

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

package/dist/files.d.ts

@@ -0,0 +1,60 @@
+export declare const FILE_DEFAULT_MAX_BYTES: number;
+export declare const FILE_HARD_MAX_BYTES: number;
+export declare const FILE_CHUNK_BYTES = 65536;
+export type FileFailure = "disabled" | "invalid_name" | "unsafe_root" | "unsafe_file" | "not_found" | "not_regular" | "too_large" | "changed" | "exists" | "busy" | "cancelled" | "incomplete" | "transfer_failed" | "commit_unconfirmed" | "publication_unknown" | "io";
+export type FileCleanupWarning = "staging_cleanup_failed";
+export declare class FileAccessError extends Error {
+    readonly code: FileFailure;
+    cleanupWarning?: FileCleanupWarning;
+    constructor(code: FileFailure);
+}
+export interface FileMetadata {
+    file: string;
+    size: number;
+    sha256: string;
+    complete: true;
+    cleanupWarning?: FileCleanupWarning;
+}
+/** Host-only authorization, supplied by a key lease for plaintext output, never caller JSON. */
+export interface FileCommitGuard {
+    check(): void;
+    commit(): void;
+}
+export interface FileInput {
+    readonly size: number;
+    readonly stream: ReadableStream<Uint8Array>;
+    /** Available only after EOF and stable-descriptor verification. Hashes actual streamed bytes. */
+    metadata(): FileMetadata;
+}
+export declare function fileName(value: unknown): string;
+/** One bounded operation. The session permits an input-to-output transformation without
+ * reacquiring the root's single transfer slot (#12/#16/#18 reuse the same byte boundary). */
+export declare class FileSession {
+    private readonly base;
+    readonly maxBytes: number;
+    readonly signal: AbortSignal;
+    private inputActive;
+    private outputActive;
+    constructor(base: string, maxBytes: number, signal: AbortSignal);
+    withInput<T>(name: unknown, job: (input: FileInput) => Promise<T>): Promise<T>;
+    /** Protected staging, incremental digest and no-overwrite atomic publication. Known sizes
+     * enforce exact counts; undefined is only for an authenticated transform whose EOF proves
+     * completeness, still bounded by maxBytes. Optional host guard spans the asynchronous link.
+     * A refusal AFTER linking is commit_unconfirmed, NOT a claim plaintext was never published. */
+    writeNew(name: unknown, stream: ReadableStream<Uint8Array>, size: number | undefined, authorization?: FileCommitGuard): Promise<FileMetadata>;
+}
+export declare class FileRoot {
+    private readonly handle;
+    readonly maxBytes: number;
+    private busy;
+    private closed;
+    private readonly lifetime;
+    private pending;
+    private constructor();
+    static open(path: string, maxBytes?: number, excludedPaths?: readonly string[]): Promise<FileRoot>;
+    transfer<T>(job: (files: FileSession) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    close(): Promise<void>;
+}
+/** Unconfigured access is absent, not a cwd/home fallback. Invalid opt-in refuses startup. */
+export declare function fileRootFromEnv(env: NodeJS.ProcessEnv, excludedPaths?: readonly string[]): Promise<FileRoot | undefined>;
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

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

package/dist/files.js

@@ -0,0 +1,355 @@
+// The file capability is explicit, server-local and Linux-only. Pin the DIRECTORY descriptor,
+// then resolve one basename through procfs and use O_NOFOLLOW on the final entry. A realpath
+// check followed by opening the original pathname would reintroduce the symlink/rename race.
+// OS account/process isolation is still required: another process with our UID can read our FDs.
+import { constants } from "node:fs";
+import { open, link, unlink, realpath } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { isAbsolute, relative, sep } from "node:path";
+export const FILE_DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+export const FILE_HARD_MAX_BYTES = 1024 * 1024 * 1024;
+export const FILE_CHUNK_BYTES = 65_536;
+export class FileAccessError extends Error {
+    code;
+    cleanupWarning;
+    constructor(code) {
+        super(`file access: ${code}`);
+        this.code = code;
+        this.name = "FileAccessError";
+    }
+}
+function checkSignal(signal) { if (signal.aborted)
+    throw new FileAccessError("cancelled"); }
+export function fileName(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value))
+        throw new FileAccessError("invalid_name");
+    return value;
+}
+function fileError(e) {
+    if (e instanceof FileAccessError)
+        return e;
+    const code = e && typeof e === "object" && "code" in e ? e.code : undefined;
+    return new FileAccessError(code === "ENOENT" ? "not_found" : code === "EEXIST" ? "exists" :
+        code === "ELOOP" ? "unsafe_file" : "io");
+}
+function checkSize(size, max) {
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new FileAccessError("incomplete");
+    if (size > max)
+        throw new FileAccessError("too_large");
+}
+/** One bounded operation. The session permits an input-to-output transformation without
+ * reacquiring the root's single transfer slot (#12/#16/#18 reuse the same byte boundary). */
+export class FileSession {
+    base;
+    maxBytes;
+    signal;
+    inputActive = false;
+    outputActive = false;
+    constructor(base, maxBytes, signal) {
+        this.base = base;
+        this.maxBytes = maxBytes;
+        this.signal = signal;
+    }
+    async withInput(name, job) {
+        const file = fileName(name);
+        checkSignal(this.signal);
+        if (this.inputActive)
+            throw new FileAccessError("busy");
+        this.inputActive = true;
+        let fh;
+        let stream;
+        try {
+            // NONBLOCK prevents a FIFO open from hanging before fstat can refuse it.
+            try {
+                fh = await open(`${this.base}/${file}`, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            }
+            catch (e) {
+                throw fileError(e);
+            }
+            const before = await fh.stat({ bigint: true });
+            if (!before.isFile())
+                throw new FileAccessError("not_regular");
+            if (before.nlink !== 1n || before.uid !== BigInt(process.getuid()))
+                throw new FileAccessError("unsafe_file");
+            if (before.size > BigInt(this.maxBytes))
+                throw new FileAccessError("too_large");
+            const size = Number(before.size);
+            checkSize(size, this.maxBytes);
+            let seen = 0;
+            let metadata;
+            const hash = createHash("sha256");
+            const handle = fh;
+            const signal = this.signal;
+            stream = new ReadableStream({
+                async pull(ctrl) {
+                    try {
+                        checkSignal(signal);
+                        // Read one extra byte to detect growth. Never enqueue bytes beyond declared size.
+                        const buf = Buffer.allocUnsafe(Math.min(FILE_CHUNK_BYTES, size - seen + 1));
+                        const { bytesRead } = await handle.read(buf, 0, buf.length, null);
+                        checkSignal(signal);
+                        if (bytesRead > size - seen)
+                            throw new FileAccessError("changed");
+                        if (bytesRead === 0) {
+                            const after = await handle.stat({ bigint: true });
+                            if (seen !== size || before.size !== after.size || before.mtimeNs !== after.mtimeNs ||
+                                before.ctimeNs !== after.ctimeNs || after.nlink !== 1n)
+                                throw new FileAccessError("changed");
+                            metadata = { file, size, sha256: hash.digest("hex"), complete: true };
+                            ctrl.close();
+                            return;
+                        }
+                        const bytes = buf.subarray(0, bytesRead);
+                        seen += bytesRead;
+                        hash.update(bytes);
+                        ctrl.enqueue(bytes);
+                    }
+                    catch (e) {
+                        ctrl.error(fileError(e));
+                    }
+                },
+            }, { highWaterMark: 0 });
+            const result = await job({ size, stream, metadata() {
+                    if (!metadata)
+                        throw new FileAccessError("incomplete");
+                    return metadata;
+                } });
+            checkSignal(this.signal);
+            return result;
+        }
+        finally {
+            // Locked streams are owned by the callback/client; it must honor signal and release them.
+            await stream?.cancel().catch(() => undefined);
+            await fh?.close();
+            this.inputActive = false;
+        }
+    }
+    /** Protected staging, incremental digest and no-overwrite atomic publication. Known sizes
+     * enforce exact counts; undefined is only for an authenticated transform whose EOF proves
+     * completeness, still bounded by maxBytes. Optional host guard spans the asynchronous link.
+     * A refusal AFTER linking is commit_unconfirmed, NOT a claim plaintext was never published. */
+    async writeNew(name, stream, size, authorization) {
+        let fh;
+        let reader;
+        let temp;
+        let claimed = false;
+        let completed;
+        let failure;
+        try {
+            const file = fileName(name);
+            if (size !== undefined)
+                checkSize(size, this.maxBytes);
+            const limit = size ?? this.maxBytes;
+            const check = () => { checkSignal(this.signal); authorization?.check(); };
+            check();
+            if (this.outputActive)
+                throw new FileAccessError("busy");
+            this.outputActive = true;
+            claimed = true;
+            temp = `${this.base}/.partial-${randomUUID()}`;
+            fh = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            reader = stream.getReader();
+            const hash = createHash("sha256");
+            let seen = 0;
+            const abort = () => { void reader.cancel().catch(() => undefined); };
+            this.signal.addEventListener("abort", abort, { once: true });
+            try {
+                for (;;) {
+                    check();
+                    let next;
+                    try {
+                        next = await reader.read();
+                    }
+                    catch {
+                        throw new FileAccessError(this.signal.aborted ? "cancelled" : "transfer_failed");
+                    }
+                    const { done, value } = next;
+                    check();
+                    if (done)
+                        break;
+                    if (!(value instanceof Uint8Array) || value.byteLength > limit - seen)
+                        throw new FileAccessError(size === undefined ? "too_large" : "incomplete");
+                    seen += value.byteLength;
+                    // Copy ONE bounded chunk before hashing/writing. A producer reusing a source buffer
+                    // cannot make the saved bytes differ from the bytes we hashed during async writes.
+                    for (let offset = 0; offset < value.byteLength;) {
+                        const chunk = Buffer.from(value.subarray(offset, Math.min(offset + FILE_CHUNK_BYTES, value.byteLength)));
+                        hash.update(chunk);
+                        // FileHandle.write may be short. Disk paces both the reader and the next copy.
+                        for (let written = 0; written < chunk.byteLength;) {
+                            check();
+                            const { bytesWritten } = await fh.write(chunk, written, chunk.byteLength - written, null);
+                            if (bytesWritten < 1)
+                                throw new FileAccessError("io");
+                            written += bytesWritten;
+                        }
+                        offset += chunk.byteLength;
+                    }
+                }
+            }
+            finally {
+                this.signal.removeEventListener("abort", abort);
+            }
+            if (size !== undefined && seen !== size)
+                throw new FileAccessError("incomplete");
+            await fh.sync();
+            const stat = await fh.stat();
+            if (stat.size !== seen || stat.nlink !== 1)
+                throw new FileAccessError("changed");
+            await fh.close();
+            fh = undefined;
+            check();
+            // Finalize exact metadata before publication. Cleanup cannot erase a known commit.
+            const metadata = { file, size: seen, sha256: hash.digest("hex"), complete: true };
+            const target = `${this.base}/${file}`;
+            try {
+                await link(temp, target);
+            }
+            catch (e) {
+                if (e && typeof e === "object" && "code" in e && e.code === "EEXIST")
+                    throw fileError(e);
+                // An error can arrive after visibility. Never automatically delete an uncertain target.
+                throw new FileAccessError("publication_unknown");
+            }
+            if (authorization) {
+                try {
+                    check();
+                    authorization.commit();
+                }
+                catch {
+                    // Preserve the guarded plaintext boundary: revoke during async link can have exposed
+                    // output. Best-effort removal is not proof that plaintext was never visible.
+                    await unlink(target).catch(() => undefined);
+                    throw new FileAccessError("commit_unconfirmed");
+                }
+            }
+            // Ordinary output commits at successful link; guarded output at synchronous authorization.
+            // Later cancellation, lease disposal or staging cleanup cannot turn that fact into failure.
+            completed = metadata;
+            return metadata;
+        }
+        catch (e) {
+            failure = fileError(e);
+            throw failure;
+        }
+        finally {
+            await reader?.cancel().catch(() => undefined);
+            try {
+                reader?.releaseLock();
+            }
+            catch { /* cancellation already requested */ }
+            if (!reader)
+                await stream.cancel().catch(() => undefined);
+            await fh?.close().catch(() => undefined);
+            if (temp) {
+                try {
+                    await unlink(temp);
+                }
+                catch {
+                    if (completed)
+                        completed.cleanupWarning = "staging_cleanup_failed";
+                    else if (failure)
+                        failure.cleanupWarning = "staging_cleanup_failed";
+                }
+            }
+            if (claimed)
+                this.outputActive = false;
+        }
+    }
+}
+export class FileRoot {
+    handle;
+    maxBytes;
+    busy = false;
+    closed = false;
+    lifetime = new AbortController();
+    pending = Promise.resolve();
+    constructor(handle, maxBytes) {
+        this.handle = handle;
+        this.maxBytes = maxBytes;
+    }
+    static async open(path, maxBytes = FILE_DEFAULT_MAX_BYTES, excludedPaths = []) {
+        if (process.platform !== "linux" || !process.getuid || !isAbsolute(path))
+            throw new FileAccessError("unsafe_root");
+        checkSize(maxBytes, FILE_HARD_MAX_BYTES);
+        if (maxBytes < 1)
+            throw new FileAccessError("too_large");
+        let handle;
+        try {
+            // Administrator config, not a caller path. Reject a symlink root; retain its descriptor.
+            handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            const st = await handle.stat();
+            if (!st.isDirectory() || st.uid !== process.getuid() || (st.mode & 0o777) !== 0o700)
+                throw new FileAccessError("unsafe_root");
+            const pinned = `/proc/self/fd/${handle.fd}`;
+            const actual = await realpath(pinned); // also proves usable procfs
+            for (const excludedPath of excludedPaths) {
+                const excluded = await realpath(excludedPath);
+                const within = (a, b) => {
+                    const rel = relative(a, b);
+                    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+                };
+                if (within(actual, excluded) || within(excluded, actual))
+                    throw new FileAccessError("unsafe_root");
+            }
+            return new FileRoot(handle, maxBytes);
+        }
+        catch {
+            await handle?.close();
+            throw new FileAccessError("unsafe_root");
+        }
+    }
+    async transfer(job, signal) {
+        if (this.closed)
+            throw new FileAccessError("disabled");
+        if (this.busy)
+            throw new FileAccessError("busy");
+        this.busy = true;
+        let done;
+        this.pending = new Promise(resolve => { done = resolve; });
+        const controller = new AbortController();
+        const forwardAbort = () => controller.abort();
+        const sources = signal ? [signal, this.lifetime.signal] : [this.lifetime.signal];
+        try {
+            for (const source of sources)
+                source.addEventListener("abort", forwardAbort, { once: true });
+            if (sources.some(source => source.aborted))
+                controller.abort();
+            checkSignal(controller.signal);
+            return await job(new FileSession(`/proc/self/fd/${this.handle.fd}`, this.maxBytes, controller.signal));
+        }
+        finally {
+            for (const source of sources)
+                source.removeEventListener("abort", forwardAbort);
+            this.busy = false;
+            done();
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.lifetime.abort();
+        await this.pending;
+        await this.handle.close();
+    }
+}
+/** Unconfigured access is absent, not a cwd/home fallback. Invalid opt-in refuses startup. */
+export async function fileRootFromEnv(env, excludedPaths = []) {
+    const path = env.EVOLVER_FILE_ROOT;
+    const max = env.EVOLVER_FILE_MAX_BYTES;
+    if (path === undefined) {
+        if (max !== undefined)
+            throw new FileAccessError("unsafe_root");
+        return undefined;
+    }
+    if (path.length === 0 || (max !== undefined && !/^[1-9][0-9]*$/.test(max)))
+        throw new FileAccessError("unsafe_root");
+    const protectedPaths = [env.EVOLVER_KEY_PATH, env.EVOLVER_APPLICATION_KEY_PATH,
+        env.EVOLVER_GROUP_CRYPTO_KEY_FILE, env.EVOLVER_LOGIN_PROFILES_PATH,
+        env.EVOLVER_HTTP_PROFILES_PATH, env.EVOLVER_TRANSACTION_POLICY_PATH, env.EVOLVER_MCP_CONFIG, ...excludedPaths]
+        .filter((p) => typeof p === "string" && p.length > 0);
+    return FileRoot.open(path, max === undefined ? FILE_DEFAULT_MAX_BYTES : Number(max), protectedPaths);
+}
+//# sourceMappingURL=files.js.map