@jinn-network/core 0.1.2-canary.bebeb033 → 0.1.2-canary.c8da24a8

package/dist/corpus-read/acquire.d.ts

@@ -3,6 +3,12 @@
  *
  * Always hash-verifies before persisting to cache.
  *
+ * The two *network* legs — the donated IPFS mirror and the operator origin —
+ * are not implemented here: they are `fetchVerifiedArtifact`, the keyless
+ * retrieval primitive (#4179). What remains in this file is the store-aware
+ * composition around it: the cache read, the self-store mirror, the route
+ * resolver, and the cache writes whose ordering the daemon owns.
+ *
  * Spec §2.3 step 4-6.
  */
 import { type AcquireResult } from './fetch-artifact.js';

package/dist/corpus-read/acquire.js

@@ -3,72 +3,68 @@
  *
  * Always hash-verifies before persisting to cache.
  *
+ * The two *network* legs — the donated IPFS mirror and the operator origin —
+ * are not implemented here: they are `fetchVerifiedArtifact`, the keyless
+ * retrieval primitive (#4179). What remains in this file is the store-aware
+ * composition around it: the cache read, the self-store mirror, the route
+ * resolver, and the cache writes whose ordering the daemon owns.
+ *
  * Spec §2.3 step 4-6.
  */
-import { createHash } from 'node:crypto';
 import { fetchArtifactContent } from './fetch-artifact.js';
+import { fetchVerifiedArtifact, verifyArtifactDigest } from './artifact-retrieval.js';
 import { AcquireError, HashMismatchError } from './types.js';
-import { classifyIpfsFetchFailure, fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
-const DONATION_ARTIFACT_ENCODING = 'jinn.artifact.donation.v1';
-function sha256Hex(buf) {
-    return createHash('sha256').update(buf).digest('hex');
-}
 /**
- * Log an IPFS read that the acquisition chain is about to fall through, unless
- * the gateway actually answered "not there" (#3441). A cap refusal is positive
- * evidence the content exists, so it must not read like an ordinary miss.
+ * Adapt a legacy `AcquireFn` to the primitive's clean seam. The legacy shape —
+ * a third `privateKey` parameter and a `Buffer | null` return — exists for
+ * older test fakes and stays confined to this file.
  */
-function warnIpfsFallThrough(subject, error) {
-    const classification = classifyIpfsFetchFailure(error);
-    if (classification === 'not-found')
-        return;
-    const detail = error instanceof Error ? error.message : String(error);
-    console.warn(`[corpus-read] IPFS source for ${subject} could not be used (${classification}), `
-        + `falling through to the next source: ${detail}`);
-}
-function decodeDonationArtifact(raw, expectedSha256) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-        throw new Error('donation artifact payload is not an object');
-    }
-    const record = raw;
-    if (record['schemaVersion'] !== DONATION_ARTIFACT_ENCODING || record['encoding'] !== DONATION_ARTIFACT_ENCODING) {
-        throw new Error('donation artifact payload has unexpected encoding');
-    }
-    if (record['sha256'] !== expectedSha256) {
-        throw new Error('donation artifact sha256 does not match requested artifact');
-    }
-    if (typeof record['data'] !== 'string') {
-        throw new Error('donation artifact payload is missing base64 data');
-    }
-    return Buffer.from(record['data'], 'base64');
+function toAcquireResultFn(acquireFn, privateKey) {
+    return async (endpoint, sha256) => {
+        const raw = await acquireFn(endpoint, sha256, privateKey);
+        if (raw === null)
+            return { ok: false, reason: 'not_found', message: 'origin returned null (404 / not found)' };
+        if (Buffer.isBuffer(raw))
+            return { ok: true, content: raw };
+        return raw;
+    };
 }
 export async function acquireArtifactContent(args) {
-    const { sha256, artifactType, access, store, selfSafeAddress, privateKey, routeResolver, envelopeCid, sources = [], ipfsGatewayUrl, ownerSafe, acquireFn = (endpoint, sha256) => fetchArtifactContent(endpoint, sha256), fetchFromIpfs = defaultFetchFromIpfs, } = args;
+    const { sha256, artifactType, access, store, selfSafeAddress, privateKey, routeResolver, envelopeCid, sources = [], ipfsGatewayUrl, ownerSafe, acquireFn = (endpoint, sha256) => fetchArtifactContent(endpoint, sha256), fetchFromIpfs, } = args;
     const now = () => new Date().toISOString();
-    // 1. Cache hit
+    // 1. Cache hit. network_artifacts is a cache, not authoritative local state:
+    // a row that does not hash to its own key is a MISS, and every leg below
+    // re-saves through INSERT OR REPLACE, so falling through repairs it. (The
+    // self-store path at step 3 throws instead, and rightly — there is no
+    // upstream to re-fetch a corrupt served_artifacts row from.)
     const cached = store.getNetworkArtifact(sha256);
     if (cached) {
-        store.touchNetworkArtifactUsage(sha256, now());
-        return {
-            sha256,
-            bytes: cached.content,
-            artifactType: cached.artifactType,
-            source: 'cache',
-            paidAmountUsdc: '0',
-            fetchedAt: cached.fetchedAt,
-            sourceOperator: cached.sourceOperator ?? undefined,
-        };
+        // Verified before the usage bump: a row we are about to discard must not
+        // have its last_used_at refreshed.
+        const verifiedCache = verifyArtifactDigest(sha256, cached.content);
+        if (verifiedCache.ok) {
+            store.touchNetworkArtifactUsage(sha256, now());
+            return {
+                sha256,
+                bytes: cached.content,
+                artifactType: cached.artifactType,
+                source: 'cache',
+                paidAmountUsdc: '0',
+                fetchedAt: cached.fetchedAt,
+                sourceOperator: cached.sourceOperator ?? undefined,
+            };
+        }
+        console.warn(`[corpus-read] cached artifact ${sha256} hashed to ${verifiedCache.actualSha256}; `
+            + 'treating the row as a miss and re-fetching');
     }
-    // 2. Public IPFS donation source.
+    // 2. Public IPFS donation source. The primitive owns the fetch, the decode,
+    // the verification, and the #3441 fall-through warning; the cache write and
+    // the mismatch-is-fatal decision stay here, where the store lives.
     const ipfsSource = sources.find((source) => source.kind === 'ipfs');
     if (ipfsSource && ipfsGatewayUrl) {
-        try {
-            const raw = await fetchFromIpfs(ipfsGatewayUrl, ipfsSource.cid);
-            const bytes = decodeDonationArtifact(raw, sha256);
-            const actualSha = sha256Hex(bytes);
-            if (actualSha !== sha256) {
-                throw new HashMismatchError(sha256, actualSha, 'ipfs', ownerSafe);
-            }
+        const retrieved = await fetchVerifiedArtifact({ sha256, artifactType }, { sources, ipfsGatewayUrl, ownerSafe, envelopeCid }, { deps: { fetchFromIpfs } });
+        if (retrieved.ok) {
+            const bytes = retrieved.artifact.bytes;
             const ts = now();
             store.saveNetworkArtifact({
                 sha256,
@@ -91,18 +87,13 @@ export async function acquireArtifactContent(args) {
                 sourceOperator: ownerSafe,
             };
         }
-        catch (err) {
-            if (err instanceof HashMismatchError)
-                throw err;
-            // Donated IPFS is an opportunistic fast path. Gateway failures and
-            // malformed donation payloads should not block the acquisition chain;
-            // only verified byte hash mismatches remain fatal.
-            //
-            // Swallowing the failure silently, though, turns a size-policy refusal or
-            // a blocked redirect into an invisible data gap (#3441). Classify before
-            // swallowing so anything that is not proven absence reaches the operator.
-            warnIpfsFallThrough(`donation artifact ${sha256}`, err);
+        if (retrieved.reason === 'digest_mismatch') {
+            throw new HashMismatchError(sha256, retrieved.mismatch.actualSha256, 'ipfs', ownerSafe);
         }
+        // Donated IPFS is an opportunistic fast path: gateway failures and
+        // malformed donation payloads fall through to the next source. Anything
+        // that was not proven absence has already reached the operator as a
+        // warning from inside the primitive (#3441).
     }
     // 3. Self-store fast path
     if (ownerSafe && ownerSafe.toLowerCase() === selfSafeAddress.toLowerCase()) {
@@ -113,9 +104,9 @@ export async function acquireArtifactContent(args) {
             // propagate the bad bytes into network_artifacts where peers can
             // fetch them. Throwing closes the cache-poisoning gap; the self-store
             // path is now hash-equivalent to origin / route-resolver.
-            const actualSha = sha256Hex(own.content);
-            if (actualSha !== sha256) {
-                throw new HashMismatchError(sha256, actualSha, 'self-store', selfSafeAddress);
+            const verified = verifyArtifactDigest(sha256, own.content);
+            if (!verified.ok) {
+                throw new HashMismatchError(sha256, verified.actualSha256, 'self-store', selfSafeAddress);
             }
             // Mirror into cache so peer asks for the same content can hit cache (provenance: self-store-mirror).
             const ts = now();
@@ -143,9 +134,9 @@ export async function acquireArtifactContent(args) {
         try {
             const out = await routeResolver.resolve({ sha256, access, requesterSafe: selfSafeAddress });
             if (out) {
-                const actualSha = sha256Hex(out.bytes);
-                if (actualSha !== sha256) {
-                    throw new HashMismatchError(sha256, actualSha, 'route-resolver', out.sourceOperator);
+                const verified = verifyArtifactDigest(sha256, out.bytes);
+                if (!verified.ok) {
+                    throw new HashMismatchError(sha256, verified.actualSha256, 'route-resolver', out.sourceOperator);
                 }
                 const ts = now();
                 store.saveNetworkArtifact({
@@ -176,36 +167,17 @@ export async function acquireArtifactContent(args) {
         }
     }
     // 5. Origin fetch
-    let bytes;
-    try {
-        const raw = await acquireFn(access.endpoint, sha256, privateKey);
-        // Accept both the legacy `Buffer | null` shape and the discriminated
-        // union from fetchArtifactContent. Buffer.isBuffer guards before we
-        // duck-type into the union.
-        if (raw === null || Buffer.isBuffer(raw)) {
-            bytes = raw;
+    const retrieved = await fetchVerifiedArtifact({ sha256, artifactType }, { endpoint: access.endpoint, ownerSafe, envelopeCid }, { deps: { fetchArtifact: toAcquireResultFn(acquireFn, privateKey) } });
+    if (!retrieved.ok) {
+        if (retrieved.reason === 'digest_mismatch') {
+            throw new HashMismatchError(sha256, retrieved.mismatch.actualSha256, 'origin', ownerSafe);
         }
-        else if (raw.ok === true) {
-            bytes = raw.content;
-        }
-        else {
-            // ok: false — preserve the reason so the caller / daemon route can
-            // surface it via AcquireError.cause.
-            throw new AcquireError(sha256, `origin fetch failed: ${raw.reason}${raw.message ? ` (${raw.message})` : ''}`, raw);
-        }
-    }
-    catch (err) {
-        if (err instanceof AcquireError)
-            throw err;
-        throw new AcquireError(sha256, 'origin fetch failed', err);
-    }
-    if (!bytes) {
-        throw new AcquireError(sha256, 'origin returned null (404 / not found)');
-    }
-    const actualSha = sha256Hex(bytes);
-    if (actualSha !== sha256) {
-        throw new HashMismatchError(sha256, actualSha, 'origin', ownerSafe);
+        // Preserve the reason token in the message so callers and the daemon route
+        // can surface which failure this was.
+        const attempt = retrieved.attempts.find((entry) => entry.leg === 'origin');
+        throw new AcquireError(sha256, `origin fetch failed: ${retrieved.reason}${attempt?.message ? ` (${attempt.message})` : ''}`, retrieved);
     }
+    const bytes = retrieved.artifact.bytes;
     const ts = now();
     store.saveNetworkArtifact({
         sha256,

package/dist/corpus-read/artifact-retrieval.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Artifact retrieval primitive — fetch by content address, verify, return bytes.
+ *
+ * One function fetches an artifact from the network legs an envelope names and
+ * hands back its bytes only after they hash to the recorded sha256, together
+ * with the provenance of the leg that produced them. A digest mismatch fails
+ * closed: the failure arm of the result union has no bytes on it at all.
+ *
+ * Keyless and filesystem-neutral by construction. The primitive itself neither
+ * accepts nor touches key material or the filesystem: it takes no store, no
+ * signer, no private key, and no path, and it performs no write of any kind.
+ * The one channel through which such material can reach a call is the caller's
+ * own `deps` seam closure — `acquire.ts` legitimately supplies one that holds a
+ * private key — and that closure is opaque here: it is invoked, never read,
+ * never logged, and never surfaced in provenance.
+ * `test/architecture/keyless-primitive.test.ts` holds the module graph to the
+ * same promise.
+ *
+ * Where the returned bytes land is the caller's decision. The daemon chain
+ * (`acquire.ts`) composes this with its byte cache; the CLI hands them to the
+ * operator; the MCP handler proxies to a daemon that runs it. None of that is
+ * this function's business.
+ *
+ * Issue #4179 (umbrella #2448 / journey spec B0c).
+ */
+import { type AcquireResult } from './fetch-artifact.js';
+import type { ArtifactSource } from './types.js';
+/**
+ * Content address of a corpus artifact: the sha256 of the bytes themselves, as
+ * recorded in the envelope's `artifact.sha256` — never an IPFS CID (artifacts
+ * stopped having CIDs post jinn-mono-vy37.1.2).
+ */
+export interface ArtifactAddress {
+    /** 64-char lowercase hex. The one thing that is trusted. */
+    sha256: string;
+    /**
+     * Declared type from the envelope. Carried into the result for the caller's
+     * convenience and never consulted during verification — an attacker-supplied
+     * label cannot influence whether bytes are admitted.
+     */
+    artifactType?: string;
+}
+/**
+ * Where the bytes might be. Every field is manifest-supplied and therefore
+ * attacker-controlled; the destination policy and the byte/redirect/deadline
+ * caps in `fetch-artifact.ts` and `ipfs.ts` are what make that safe.
+ */
+export interface ArtifactLocators {
+    /** Donated IPFS sources — the envelope's `artifact.sources` entries. */
+    sources?: readonly ArtifactSource[];
+    /** Gateway base for the IPFS leg. The leg is skipped when this is absent. */
+    ipfsGatewayUrl?: string;
+    /** HTTP origin — the envelope's `artifact.access.endpoint`. */
+    endpoint?: string;
+    /** Envelope CID this artifact was named by. Provenance only. */
+    envelopeCid?: string;
+    /** Publishing operator's Safe, when known. Provenance and attribution only. */
+    ownerSafe?: string;
+}
+export interface FetchVerifiedArtifactOptions {
+    /**
+     * Injection seams, mirroring the `acquire.ts` precedent so tests need no
+     * module mock. A caller that needs to bound or redirect a leg replaces the
+     * leg — there is no separate options passthrough, because no call site wants
+     * the default transport with different bounds.
+     */
+    deps?: {
+        fetchArtifact?: (endpoint: string, sha256: string) => Promise<AcquireResult>;
+        fetchFromIpfs?: (gatewayUrl: string, cid: string) => Promise<unknown>;
+        /** Clock seam for `fetchedAt`. */
+        now?: () => string;
+    };
+}
+/** One leg's outcome, recorded whether it succeeded, was skipped, or failed. */
+export interface ArtifactFetchAttempt {
+    readonly leg: 'ipfs' | 'origin';
+    /** `ipfs://<cid>` or the exact URL `buildArtifactUrl` produced; empty when skipped. */
+    readonly sourceUri: string;
+    readonly outcome: 'verified' | 'skipped' | 'failed' | 'digest_mismatch';
+    /**
+     * Present on `failed`; the classified reason, never a raw string match.
+     * `digest_mismatch` is excluded because `refuse()` records that outcome with
+     * no `reason` field — no attempt ever carries the token, and saying so here
+     * is what lets the failure union below narrow without a cast.
+     */
+    readonly reason?: Exclude<ArtifactFetchFailureReason, 'digest_mismatch'>;
+    readonly message?: string;
+}
+export interface ArtifactProvenance {
+    /** Which leg produced the admitted bytes. */
+    readonly source: 'ipfs' | 'origin';
+    readonly sourceUri: string;
+    /** Always 'sha256'. Explicit so the record does not silently mean "some digest". */
+    readonly digestAlgorithm: 'sha256';
+    /** ISO-8601 instant the bytes were verified, not when they were requested. */
+    readonly fetchedAt: string;
+    readonly sourceOperator?: string;
+    readonly envelopeCid?: string;
+    /** Every leg tried, in order. Legible even on the happy path. */
+    readonly attempts: readonly ArtifactFetchAttempt[];
+}
+export interface VerifiedArtifact {
+    readonly sha256: string;
+    /** Verified bytes, in memory. Never a path, never a handle. */
+    readonly bytes: Buffer;
+    readonly artifactType: string;
+    readonly provenance: ArtifactProvenance;
+}
+export type ArtifactFetchFailureReason = 
+/** Bytes arrived and did not hash to the address. */
+'digest_mismatch'
+/** Every attempted leg answered, and every answer was absence. */
+ | 'not_found'
+/** Nothing was supplied to try. */
+ | 'no_locator'
+/** Destination policy refused an origin or a redirect hop. */
+ | 'blocked' | 'too_large' | 'timeout'
+/** Transport failure — nothing was learned about whether the content exists. */
+ | 'unavailable'
+/**
+ * A locator resolved and what it served is permanently not this artifact —
+ * a broken donation payload. Conclusive absence AT THAT LOCATOR, so it is
+ * not retryable; never conclusive globally, so it never outranks a leg that
+ * learned nothing (#3441).
+ */
+ | 'malformed_payload';
+/** Evidence, not content. Present on `digest_mismatch` and only there. */
+export interface ArtifactDigestMismatch {
+    readonly expectedSha256: string;
+    readonly actualSha256: string;
+    readonly sourceUri: string;
+    readonly sourceOperator?: string;
+}
+interface FetchVerifiedArtifactFailureBase {
+    readonly ok: false;
+    readonly sha256: string;
+    /** Derived from `reason`, never caller-supplied. */
+    readonly retryable: boolean;
+    readonly message: string;
+    readonly attempts: readonly ArtifactFetchAttempt[];
+}
+/**
+ * Discriminated on `reason` so the compiler, not a constructor comment, carries
+ * the invariant that `digest_mismatch` always ships its evidence. `refuse()` is
+ * the sole producer of that reason and has always set `mismatch`; before this
+ * split, callers reading the evidence had to assert it with `!`.
+ */
+export type FetchVerifiedArtifactFailure = (FetchVerifiedArtifactFailureBase & {
+    readonly reason: 'digest_mismatch';
+    readonly mismatch: ArtifactDigestMismatch;
+}) | (FetchVerifiedArtifactFailureBase & {
+    readonly reason: Exclude<ArtifactFetchFailureReason, 'digest_mismatch'>;
+    readonly mismatch?: undefined;
+});
+export type FetchVerifiedArtifactResult = {
+    readonly ok: true;
+    readonly artifact: VerifiedArtifact;
+} | FetchVerifiedArtifactFailure;
+/**
+ * The one digest check in the system. Legs that already hold bytes — the byte
+ * cache, the self-store, a route resolver, the MCP daemon proxy — call this
+ * rather than writing `createHash('sha256')` out again.
+ */
+export declare function verifyArtifactDigest(expectedSha256: string, bytes: Buffer): {
+    ok: true;
+} | {
+    ok: false;
+    actualSha256: string;
+};
+/**
+ * Fetch an artifact by content address and return its bytes only after they
+ * hash to that address.
+ *
+ * Legs run in the order the daemon chain has always used: the free donated IPFS
+ * mirror first, the operator's HTTP origin second. A leg with no locator is
+ * *skipped*, not failed. A digest mismatch on any leg fails the whole call and
+ * does not fall through — the bytes are wrong or hostile, and the next locator
+ * cannot make them right.
+ */
+export declare function fetchVerifiedArtifact(address: ArtifactAddress, locators: ArtifactLocators, options?: FetchVerifiedArtifactOptions): Promise<FetchVerifiedArtifactResult>;
+export {};

package/dist/corpus-read/artifact-retrieval.js

@@ -0,0 +1,268 @@
+/**
+ * Artifact retrieval primitive — fetch by content address, verify, return bytes.
+ *
+ * One function fetches an artifact from the network legs an envelope names and
+ * hands back its bytes only after they hash to the recorded sha256, together
+ * with the provenance of the leg that produced them. A digest mismatch fails
+ * closed: the failure arm of the result union has no bytes on it at all.
+ *
+ * Keyless and filesystem-neutral by construction. The primitive itself neither
+ * accepts nor touches key material or the filesystem: it takes no store, no
+ * signer, no private key, and no path, and it performs no write of any kind.
+ * The one channel through which such material can reach a call is the caller's
+ * own `deps` seam closure — `acquire.ts` legitimately supplies one that holds a
+ * private key — and that closure is opaque here: it is invoked, never read,
+ * never logged, and never surfaced in provenance.
+ * `test/architecture/keyless-primitive.test.ts` holds the module graph to the
+ * same promise.
+ *
+ * Where the returned bytes land is the caller's decision. The daemon chain
+ * (`acquire.ts`) composes this with its byte cache; the CLI hands them to the
+ * operator; the MCP handler proxies to a daemon that runs it. None of that is
+ * this function's business.
+ *
+ * Issue #4179 (umbrella #2448 / journey spec B0c).
+ */
+import { createHash } from 'node:crypto';
+import { buildArtifactUrl, fetchArtifactContent, } from './fetch-artifact.js';
+import { classifyIpfsFetchFailure, fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
+const DONATION_ARTIFACT_ENCODING = 'jinn.artifact.donation.v1';
+/** Nothing that was learned tells us to stop; everything else does. */
+const RETRYABLE_REASONS = new Set([
+    'timeout',
+    'unavailable',
+]);
+/** Reasons that are positive proof of absence at the leg that reported them. */
+const CONCLUSIVE_ABSENCE = new Set([
+    'not_found',
+    'malformed_payload',
+]);
+/**
+ * The one digest check in the system. Legs that already hold bytes — the byte
+ * cache, the self-store, a route resolver, the MCP daemon proxy — call this
+ * rather than writing `createHash('sha256')` out again.
+ */
+export function verifyArtifactDigest(expectedSha256, bytes) {
+    const actualSha256 = createHash('sha256').update(bytes).digest('hex');
+    return actualSha256 === expectedSha256 ? { ok: true } : { ok: false, actualSha256 };
+}
+/**
+ * Log an IPFS read the retrieval is about to fall through, unless the gateway
+ * actually answered "not there" (#3441). A cap refusal is positive evidence the
+ * content exists, so it must not read like an ordinary miss.
+ */
+function warnIpfsFallThrough(subject, error) {
+    // A broken donation is not the ordinary absence #3441 carved out of the
+    // warning, so it still warns — but it must not read as a transport failure.
+    const classification = error instanceof DonationDecodeError
+        ? 'malformed-payload'
+        : classifyIpfsFetchFailure(error);
+    if (classification === 'not-found')
+        return;
+    const detail = error instanceof Error ? error.message : String(error);
+    console.warn(`[corpus-read] IPFS source for ${subject} could not be used (${classification}), `
+        + `falling through to the next source: ${detail}`);
+}
+/**
+ * A donation payload that will never decode into this artifact. Distinct from a
+ * gateway transport failure: the CID resolved, and what it resolved to is not
+ * the requested bytes — including a valid donation for a *different* artifact.
+ */
+class DonationDecodeError extends Error {
+    name = 'DonationDecodeError';
+}
+/**
+ * Decode a `jinn.artifact.donation.v1` payload into its raw bytes.
+ *
+ * Moved verbatim from `acquire.ts`. The `schemaVersion` check compares against
+ * the encoding constant — the published fixtures set both fields to that same
+ * string, so the comparison is load-bearing as written and is not "corrected"
+ * here.
+ */
+function decodeDonationArtifact(raw, expectedSha256) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new DonationDecodeError('donation artifact payload is not an object');
+    }
+    const record = raw;
+    if (record['schemaVersion'] !== DONATION_ARTIFACT_ENCODING || record['encoding'] !== DONATION_ARTIFACT_ENCODING) {
+        throw new DonationDecodeError('donation artifact payload has unexpected encoding');
+    }
+    if (record['sha256'] !== expectedSha256) {
+        throw new DonationDecodeError('donation artifact sha256 does not match requested artifact');
+    }
+    if (typeof record['data'] !== 'string') {
+        throw new DonationDecodeError('donation artifact payload is missing base64 data');
+    }
+    return Buffer.from(record['data'], 'base64');
+}
+/** `fetchArtifactContent`'s vocabulary → the primitive's. */
+function originReason(reason) {
+    return reason === 'network_error' ? 'unavailable' : reason;
+}
+/** `classifyIpfsFetchFailure`'s hyphenated vocabulary → the primitive's. */
+function ipfsReason(classification) {
+    if (classification === 'too-large')
+        return 'too_large';
+    if (classification === 'not-found')
+        return 'not_found';
+    return 'unavailable';
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Fetch an artifact by content address and return its bytes only after they
+ * hash to that address.
+ *
+ * Legs run in the order the daemon chain has always used: the free donated IPFS
+ * mirror first, the operator's HTTP origin second. A leg with no locator is
+ * *skipped*, not failed. A digest mismatch on any leg fails the whole call and
+ * does not fall through — the bytes are wrong or hostile, and the next locator
+ * cannot make them right.
+ */
+export async function fetchVerifiedArtifact(address, locators, options) {
+    const { sha256, artifactType } = address;
+    const { sources = [], ipfsGatewayUrl, endpoint, envelopeCid, ownerSafe } = locators;
+    const fetchIpfs = options?.deps?.fetchFromIpfs ?? defaultFetchFromIpfs;
+    const fetchOrigin = options?.deps?.fetchArtifact ?? fetchArtifactContent;
+    const now = options?.deps?.now ?? (() => new Date().toISOString());
+    const attempts = [];
+    const admit = (source, sourceUri, bytes) => {
+        attempts.push({ leg: source, sourceUri, outcome: 'verified' });
+        return {
+            ok: true,
+            artifact: {
+                sha256,
+                bytes,
+                artifactType: artifactType ?? 'unknown',
+                provenance: {
+                    source,
+                    sourceUri,
+                    digestAlgorithm: 'sha256',
+                    fetchedAt: now(),
+                    ...(ownerSafe ? { sourceOperator: ownerSafe } : {}),
+                    ...(envelopeCid ? { envelopeCid } : {}),
+                    attempts,
+                },
+            },
+        };
+    };
+    const refuse = (leg, sourceUri, actualSha256) => {
+        attempts.push({ leg, sourceUri, outcome: 'digest_mismatch' });
+        return {
+            ok: false,
+            sha256,
+            reason: 'digest_mismatch',
+            retryable: false,
+            message: `artifact ${sha256} from ${sourceUri} hashed to ${actualSha256}; `
+                + 'the bytes were discarded',
+            attempts,
+            mismatch: {
+                expectedSha256: sha256,
+                actualSha256,
+                sourceUri,
+                ...(ownerSafe ? { sourceOperator: ownerSafe } : {}),
+            },
+        };
+    };
+    // 1. Donated IPFS mirror — free and public, so it goes first.
+    const ipfsSource = sources.find((source) => source.kind === 'ipfs');
+    if (ipfsSource && ipfsGatewayUrl) {
+        const sourceUri = `ipfs://${ipfsSource.cid}`;
+        try {
+            const raw = await fetchIpfs(ipfsGatewayUrl, ipfsSource.cid);
+            const bytes = decodeDonationArtifact(raw, sha256);
+            const verified = verifyArtifactDigest(sha256, bytes);
+            if (!verified.ok)
+                return refuse('ipfs', sourceUri, verified.actualSha256);
+            return admit('ipfs', sourceUri, bytes);
+        }
+        catch (err) {
+            // Neither a gateway failure nor a malformed donation payload is a verdict
+            // on the artifact *globally*, so both fall through and let the next
+            // locator answer. They differ in what they proved here: a transport
+            // failure learned nothing, while a payload that will never decode into
+            // this artifact is absence at this locator — hence the split reason. Both
+            // still warn; only a gateway's own "not there" is silent (#3441).
+            warnIpfsFallThrough(`donation artifact ${sha256}`, err);
+            attempts.push({
+                leg: 'ipfs',
+                sourceUri,
+                outcome: 'failed',
+                reason: err instanceof DonationDecodeError
+                    ? 'malformed_payload'
+                    : ipfsReason(classifyIpfsFetchFailure(err)),
+                message: errorMessage(err),
+            });
+        }
+    }
+    else {
+        attempts.push({ leg: 'ipfs', sourceUri: '', outcome: 'skipped' });
+    }
+    // 2. Operator HTTP origin.
+    if (endpoint) {
+        const sourceUri = buildArtifactUrl(endpoint, sha256);
+        let outcome;
+        try {
+            outcome = await fetchOrigin(endpoint, sha256);
+        }
+        catch (err) {
+            outcome = { ok: false, reason: 'network_error', message: errorMessage(err) };
+        }
+        if (outcome.ok) {
+            const verified = verifyArtifactDigest(sha256, outcome.content);
+            if (!verified.ok)
+                return refuse('origin', sourceUri, verified.actualSha256);
+            return admit('origin', sourceUri, outcome.content);
+        }
+        attempts.push({
+            leg: 'origin',
+            sourceUri,
+            outcome: 'failed',
+            reason: originReason(outcome.reason),
+            ...(outcome.message ? { message: outcome.message } : {}),
+        });
+    }
+    else {
+        attempts.push({ leg: 'origin', sourceUri: '', outcome: 'skipped' });
+    }
+    // Nothing verified. Absence is only claimed when every attempted leg said so:
+    // one inconclusive leg means we learned nothing about existence (#3441).
+    const failures = attempts.filter((attempt) => attempt.outcome === 'failed');
+    if (failures.length === 0) {
+        // Name why each leg was skipped rather than assuming both locators were
+        // absent: donated sources with no gateway to read them through is its own
+        // case, and reporting it as "no donated IPFS source" is simply wrong.
+        const missing = [
+            ipfsSource
+                ? 'a donated IPFS source but no gateway URL to read it through'
+                : 'no donated IPFS source',
+            'no origin endpoint',
+        ];
+        return {
+            ok: false,
+            sha256,
+            reason: 'no_locator',
+            retryable: false,
+            message: `artifact ${sha256} has no locator to try: ${missing.join(', and ')}`,
+            attempts,
+        };
+    }
+    // When more than one leg fails inconclusively, the last one wins. Legs run
+    // cheapest-first — the opportunistic donated mirror, then the operator's own
+    // origin — so the last leg to answer is the artifact's actual home, and its
+    // reason is the one the operator can act on.
+    // Absence is a set, not one literal: a leg that resolved and served bytes that
+    // are permanently not this artifact answered as conclusively as a 404 did.
+    const inconclusive = failures.filter((attempt) => !CONCLUSIVE_ABSENCE.has(attempt.reason));
+    const reason = (inconclusive.length > 0 ? inconclusive : failures).at(-1).reason;
+    return {
+        ok: false,
+        sha256,
+        reason,
+        retryable: RETRYABLE_REASONS.has(reason),
+        message: `artifact ${sha256} could not be retrieved (${reason}) from `
+            + failures.map((attempt) => `${attempt.sourceUri}: ${attempt.reason}`).join('; '),
+        attempts,
+    };
+}

package/dist/corpus-read/cache.d.ts

@@ -1,14 +1,13 @@
 /**
- * Corpus cache helpers.
+ * Corpus cache is not a public helper surface.
  *
  * The corpus library reuses the existing `network_artifacts` and `served_artifacts`
- * tables on the daemon's `Store`. There is no separate corpus cache layer — the
- * acquire chain in `acquire.ts` is the only writer/reader. This module exposes
- * thin convenience helpers for higher-level code that wants to inspect or
- * pre-populate the cache without going through `acquireArtifactContent`.
+ * tables on the daemon's `Store`. There is no separate corpus cache API —
+ * `acquireArtifactContent` is the only writer/reader, and it digest-checks cached
+ * rows before serving them. Do not reintroduce `getCachedArtifact` /
+ * `hasCachedArtifact`: they returned unverified `network_artifacts` rows and
+ * would reopen the byte-admission gap #4359 closed (#4500).
  *
  * Spec: spec/2026-04-30-phase-a-umbrella.md §2.4 (caching semantics).
  */
-import type { CorpusStorePort, NetworkArtifactRow } from './types.js';
-export declare function getCachedArtifact(store: CorpusStorePort, sha256: string): NetworkArtifactRow | null;
-export declare function hasCachedArtifact(store: CorpusStorePort, sha256: string): boolean;
+export {};

package/dist/corpus-read/cache.js

@@ -1,17 +1 @@
-/**
- * Corpus cache helpers.
- *
- * The corpus library reuses the existing `network_artifacts` and `served_artifacts`
- * tables on the daemon's `Store`. There is no separate corpus cache layer — the
- * acquire chain in `acquire.ts` is the only writer/reader. This module exposes
- * thin convenience helpers for higher-level code that wants to inspect or
- * pre-populate the cache without going through `acquireArtifactContent`.
- *
- * Spec: spec/2026-04-30-phase-a-umbrella.md §2.4 (caching semantics).
- */
-export function getCachedArtifact(store, sha256) {
-    return store.getNetworkArtifact(sha256);
-}
-export function hasCachedArtifact(store, sha256) {
-    return store.getNetworkArtifact(sha256) !== null;
-}
+export {};

package/dist/corpus-read/env.d.ts

@@ -0,0 +1,9 @@
+/** Environment-variable parsing shared by the corpus read paths. */
+/**
+ * `minimum` is 0 where the bound reads `0` as "disabled" (a whole-operation
+ * timeout, or a redirect cap of zero meaning "follow none"), and 1 for a byte
+ * cap, where zero would not disable anything — it would reject every response
+ * as `too_large`. A foot-gun that silently stops all acquisition is worse than
+ * ignoring the value, so an out-of-range setting falls back to the default.
+ */
+export declare function envInteger(name: string, fallback: number, minimum?: number): number;

package/dist/corpus-read/env.js

@@ -0,0 +1,15 @@
+/** Environment-variable parsing shared by the corpus read paths. */
+/**
+ * `minimum` is 0 where the bound reads `0` as "disabled" (a whole-operation
+ * timeout, or a redirect cap of zero meaning "follow none"), and 1 for a byte
+ * cap, where zero would not disable anything — it would reject every response
+ * as `too_large`. A foot-gun that silently stops all acquisition is worse than
+ * ignoring the value, so an out-of-range setting falls back to the default.
+ */
+export function envInteger(name, fallback, minimum = 0) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed >= minimum ? parsed : fallback;
+}

package/dist/corpus-read/fetch-artifact.js

@@ -23,6 +23,7 @@
  * - the body is streamed through a byte counter and abandoned the moment it
  *   exceeds the cap, so an oversized response is never fully buffered.
  */
+import { envInteger } from './env.js';
 import { resolvePublicHttpDestination, ProhibitedDestinationError, } from './origin-guard.js';
 import { pinnedFetch } from './pinned-fetch.js';
 /** 32 MiB. Artifacts are solution/evidence payloads, not disk images. */
@@ -34,20 +35,6 @@ class TimeoutError extends Error {
 }
 class TooLargeError extends Error {
 }
-/**
- * `minimum` is 0 where the bound reads `0` as "disabled" (the timeout, and a
- * redirect cap of zero meaning "follow none"), and 1 for the byte cap, where
- * zero would not disable anything — it would reject every artifact as
- * `too_large`. A foot-gun that silently stops all acquisition is worse than
- * ignoring the value, so an out-of-range setting falls back to the default.
- */
-function envInteger(name, fallback, minimum = 0) {
-    const raw = process.env[name];
-    if (raw === undefined || raw.trim() === '')
-        return fallback;
-    const parsed = Number(raw);
-    return Number.isInteger(parsed) && parsed >= minimum ? parsed : fallback;
-}
 function envFlag(name) {
     const raw = process.env[name];
     if (raw === undefined)

package/dist/corpus-read/index.d.ts

@@ -1,5 +1,5 @@
 export * from './acquire.js';
-export * from './cache.js';
+export * from './artifact-retrieval.js';
 export * from './capture-meta.js';
 export * from './create-corpus.js';
 export * from './fetch-artifact.js';

package/dist/corpus-read/index.js

@@ -1,5 +1,5 @@
 export * from './acquire.js';
-export * from './cache.js';
+export * from './artifact-retrieval.js';
 export * from './capture-meta.js';
 export * from './create-corpus.js';
 export * from './fetch-artifact.js';

package/dist/corpus-read/ipfs.d.ts

@@ -56,6 +56,37 @@ export declare class IpfsFetchFailedError extends Error {
  * default fetch also tries the `ipfs.io` fallback, which typically stalls into a 504 or an abort
  * for an unpinned digest rather than answering 404. Such a run classifies `'unavailable'` — the
  * safe direction, since absence is never claimed without proof of it.
+ *
+ * That near-unreachability was weighed and is ACCEPTED (#3477). Three loosenings were considered
+ * and all three are rejected:
+ *
+ *   - Treat a primary-gateway 404 as authoritative absence. A gateway 404 means *that gateway did
+ *     not resolve the CID inside its own timeout*, not that the content is absent from the
+ *     network. Elevating it to a global absence claim is strictly weaker evidence than the current
+ *     rule, in the exact direction #2647's FAILURE IS NOT ABSENCE exists to forbid.
+ *   - Surface per-gateway evidence to the caller. Nothing to build: {@link
+ *     IpfsFetchFailedError.causes} is already a per-candidate array in attempt order, and the
+ *     aggregate message names each candidate. So the strictness costs no INFORMATION — only the
+ *     convenience of a single verdict, which any caller needing finer granularity can bypass.
+ *   - Separate the never-reached fallback out as its own case, distinct from a fallback that
+ *     answered something other than 404. A candidate the whole-operation deadline never reached
+ *     is not evidence of absence — the
+ *     un-attempted gateway could have served it. Counting a non-attempt as absence-supporting is
+ *     the first loosening with an extra step.
+ *
+ * The asymmetry is what settles it. Classifying genuine absence as `'unavailable'` costs one
+ * warning line and a retry on a later tick: cheap and self-correcting. Classifying a mere
+ * non-answer as `'not-found'` costs silent treatment as absent, no retry signal, and a data gap
+ * indistinguishable from real data: expensive, permanent, invisible.
+ *
+ * The strictness is not free: control flow does branch on `'not-found'`, so its cost is noisier
+ * `'unavailable'` warnings for content that is genuinely absent, rather than none —
+ * `buildFetchIpfsBytes` (returns `undefined` instead of the refusal string) and `narrowIpfsBytes`
+ * (silent instead of `logger.warn`) in `operator/src/daemon/composition-root.ts`;
+ * `warnIpfsFallThrough` (silent instead of `console.warn`) and `ipfsReason` (reason `not_found`
+ * instead of `too_large` / `unavailable`) in `./artifact-retrieval.ts`; and the task, trajectory,
+ * and source-bundle reads in `operator/src/conformance/harness.ts` (silent instead of
+ * `console.warn`).
  */
 export declare function classifyIpfsFetchFailure(error: unknown): 'too-large' | 'not-found' | 'unavailable';
 export declare function normalizeIpfsGatewayBase(gatewayUrl: string): string;
@@ -74,7 +105,14 @@ export type FetchFromIpfsOptions = {
      * {@link DEFAULT_MAX_IPFS_RESPONSE_BYTES}. Raise it only for a call site that
      * legitimately reads larger payloads (#3441) — the default is sized for JSON
      * envelopes and source files, and a caller that raises it accepts buffering
-     * that many bytes. Values below 1 fall back to the default.
+     * that many bytes. Values below 1 fall back to the env, then the default.
+     *
+     * An operator may move the *default* with `JINN_IPFS_MAX_RESPONSE_BYTES`
+     * (#3453). An explicit bound here wins over it, so the env cannot clamp a
+     * call site that already states its own — concretely, it does not reach
+     * `fetchTrajectoryFromIpfs`'s 64 MiB (`MAX_TRAJECTORY_IPFS_RESPONSE_BYTES`,
+     * `operator/src/adapters/mech/ipfs.ts`). Making it a ceiling instead would
+     * make the raise-the-cap intent this option exists for inexpressible.
      */
     maxResponseBytes?: number;
 };

package/dist/corpus-read/ipfs.js

@@ -1,3 +1,4 @@
+import { envInteger } from './env.js';
 const IPFS_FETCH_TIMEOUT_MS = 15_000;
 /**
  * Bound on one whole `fetchFromIpfs` / `fetchBytesFromIpfs` call. The
@@ -79,6 +80,37 @@ export class IpfsFetchFailedError extends Error {
  * default fetch also tries the `ipfs.io` fallback, which typically stalls into a 504 or an abort
  * for an unpinned digest rather than answering 404. Such a run classifies `'unavailable'` — the
  * safe direction, since absence is never claimed without proof of it.
+ *
+ * That near-unreachability was weighed and is ACCEPTED (#3477). Three loosenings were considered
+ * and all three are rejected:
+ *
+ *   - Treat a primary-gateway 404 as authoritative absence. A gateway 404 means *that gateway did
+ *     not resolve the CID inside its own timeout*, not that the content is absent from the
+ *     network. Elevating it to a global absence claim is strictly weaker evidence than the current
+ *     rule, in the exact direction #2647's FAILURE IS NOT ABSENCE exists to forbid.
+ *   - Surface per-gateway evidence to the caller. Nothing to build: {@link
+ *     IpfsFetchFailedError.causes} is already a per-candidate array in attempt order, and the
+ *     aggregate message names each candidate. So the strictness costs no INFORMATION — only the
+ *     convenience of a single verdict, which any caller needing finer granularity can bypass.
+ *   - Separate the never-reached fallback out as its own case, distinct from a fallback that
+ *     answered something other than 404. A candidate the whole-operation deadline never reached
+ *     is not evidence of absence — the
+ *     un-attempted gateway could have served it. Counting a non-attempt as absence-supporting is
+ *     the first loosening with an extra step.
+ *
+ * The asymmetry is what settles it. Classifying genuine absence as `'unavailable'` costs one
+ * warning line and a retry on a later tick: cheap and self-correcting. Classifying a mere
+ * non-answer as `'not-found'` costs silent treatment as absent, no retry signal, and a data gap
+ * indistinguishable from real data: expensive, permanent, invisible.
+ *
+ * The strictness is not free: control flow does branch on `'not-found'`, so its cost is noisier
+ * `'unavailable'` warnings for content that is genuinely absent, rather than none —
+ * `buildFetchIpfsBytes` (returns `undefined` instead of the refusal string) and `narrowIpfsBytes`
+ * (silent instead of `logger.warn`) in `operator/src/daemon/composition-root.ts`;
+ * `warnIpfsFallThrough` (silent instead of `console.warn`) and `ipfsReason` (reason `not_found`
+ * instead of `too_large` / `unavailable`) in `./artifact-retrieval.ts`; and the task, trajectory,
+ * and source-bundle reads in `operator/src/conformance/harness.ts` (silent instead of
+ * `console.warn`).
  */
 export function classifyIpfsFetchFailure(error) {
     const causes = error instanceof IpfsFetchFailedError ? error.causes : [error];
@@ -93,20 +125,32 @@ export function normalizeIpfsGatewayBase(gatewayUrl) {
     let normalized = gatewayUrl.trim();
     if (normalized === '')
         normalized = 'https://gateway.autonolas.tech';
-    // Drop any userinfo at the source. `fetch` rejects a credentialed URL
-    // outright, and its own error message quotes the URL back — so a gateway
-    // configured Infura-style would otherwise put its secret into every
-    // aggregated fetch error, which callers log.
     try {
         const parsed = new URL(normalized);
-        if (parsed.username !== '' || parsed.password !== '') {
-            parsed.username = '';
-            parsed.password = '';
-            normalized = parsed.toString();
-        }
+        // Drop any userinfo at the source. `fetch` rejects a credentialed URL
+        // outright, and its own error message quotes the URL back — so a gateway
+        // configured Infura-style would otherwise put its secret into every
+        // aggregated fetch error, which callers log.
+        parsed.username = '';
+        parsed.password = '';
+        // A fragment is never transmitted to a server, and treating it as part of
+        // the base corrupted the `/ipfs` suffix test into appending a second
+        // segment (`…/ipfs#frag` → `…/ipfs#frag/ipfs/`). Dropping it is the only
+        // reading that is both correct and lossless in transit.
+        parsed.hash = '';
+        // Normalize on the parsed path, not the raw string: a query-bearing base
+        // otherwise had `/ipfs/` spliced on after the query, putting the CID
+        // inside the query string (#3452).
+        let path = parsed.pathname.replace(/\/+$/, '');
+        if (!path.toLowerCase().endsWith('/ipfs'))
+            path = `${path}/ipfs`;
+        parsed.pathname = `${path}/`;
+        return parsed.toString();
     }
     catch {
-        // Not an absolute URL; leave it to the caller's own failure path.
+        // Not an absolute URL; leave it to the caller's own failure path, which
+        // reports it as a per-candidate `candidate URL could not be parsed`
+        // instead of escaping as a bare TypeError.
     }
     normalized = normalized.replace(/\/+$/, '');
     if (!normalized.toLowerCase().endsWith('/ipfs'))
@@ -190,7 +234,51 @@ async function discardBody(response) {
         // A body that refuses to cancel is not worth failing the request over.
     }
 }
-/** Read a response body as bytes, refusing anything past `maxBytes`. */
+/**
+ * The exact decoded length this response promises, or `undefined` when it
+ * promises nothing usable (#3759).
+ *
+ * `content-encoding` is the trap: with one set, `content-length` describes
+ * *wire* bytes, and the reader hands back the decoded ones — a gzipped 200 KB
+ * JSON body declares ~230. Pre-sizing from that is not a pessimization, it is
+ * a buffer guaranteed to overflow, so the fast path is gated on the encoding
+ * being absent or `identity`. The raw header is read rather than
+ * `Number(header)` because `Number(null)` is `0`, which cannot be told from a
+ * genuinely declared zero.
+ */
+function exactDecodedLength(response, maxBytes) {
+    const encoding = response.headers.get('content-encoding');
+    if (encoding !== null && encoding.trim().toLowerCase() !== 'identity')
+        return undefined;
+    const raw = response.headers.get('content-length');
+    if (raw === null || raw.trim() === '')
+        return undefined;
+    const declared = Number(raw);
+    if (!Number.isInteger(declared) || declared < 0 || declared > maxBytes)
+        return undefined;
+    return declared;
+}
+/**
+ * Read a response body as bytes, refusing anything past `maxBytes`.
+ *
+ * Peak resident bytes, not memcpy count, is what the pre-sizing below buys.
+ * The stream has already allocated each chunk either way, and the join is the
+ * single copy in both designs — but the chunk-list path holds every chunk live
+ * *while* it allocates and fills the joined buffer, so it peaks at roughly
+ * twice the payload: ~128 MiB at `fetchTrajectoryFromIpfs`'s 64 MiB bound
+ * (measured), against ~1x live for the pre-sized path.
+ *
+ * The honest caveat: the fast path is gated on the absence of a content
+ * encoding, and gateways generally compress JSON — so it will rarely engage on
+ * the very trajectory read that motivated the bound. The win is real for the
+ * raw-bytes path (source files, sealed documents, envelopes) and
+ * correct-but-inert for compressed JSON.
+ *
+ * Out of scope, and larger than what this removes: `fetchJson` decodes these
+ * bytes into a UTF-16 string (up to 2x the byte length) and then `JSON.parse`s
+ * that into an object graph, all while the bytes are still live. Bringing that
+ * down means streaming JSON parsing, which is a rewrite rather than a fix.
+ */
 async function readBoundedBytes(response, maxBytes) {
     const declared = Number(response.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
@@ -201,6 +289,9 @@ async function readBoundedBytes(response, maxBytes) {
     if (!body)
         return new Uint8Array(0);
     const reader = body.getReader();
+    const exact = exactDecodedLength(response, maxBytes);
+    let buffer = exact === undefined ? undefined : new Uint8Array(exact);
+    let written = 0;
     const chunks = [];
     let total = 0;
     try {
@@ -211,9 +302,27 @@ async function readBoundedBytes(response, maxBytes) {
             if (!value)
                 continue;
             total += value.byteLength;
+            // The cumulative counter stays the authority on the cap. The pre-sized
+            // buffer's own length is never it — a lying `content-length` must not be
+            // able to widen or narrow the bound.
             if (total > maxBytes) {
                 throw new IpfsResponseTooLargeError(maxBytes);
             }
+            if (buffer !== undefined) {
+                if (written + value.byteLength <= buffer.length) {
+                    buffer.set(value, written);
+                    written += value.byteLength;
+                    continue;
+                }
+                // The body outran what it declared, on an identity response. Fall back
+                // in place: what was written becomes the first chunk-list entry and
+                // the read continues exactly as it did before. Peak on this anomalous
+                // path is 2x — today's behaviour, so no regression and no new failure
+                // mode. (`subarray` is right here: the pre-sized buffer is dropped
+                // straight after, so retaining its backing store costs nothing.)
+                chunks.push(buffer.subarray(0, written));
+                buffer = undefined;
+            }
             chunks.push(value);
         }
     }
@@ -225,6 +334,15 @@ async function readBoundedBytes(response, maxBytes) {
             // Already terminal; the read result (or throw) above is what matters.
         }
     }
+    if (buffer !== undefined) {
+        // A short body is not reachable through `fetch` — undici rejects a body
+        // that ends early with `TypeError: terminated` — but returning trailing
+        // zeros would be wrong if it ever were, and the guard costs one branch.
+        // `slice`, never `subarray`: a view would retain the whole pre-sized
+        // backing store and silently defeat this change on the one path where it
+        // matters.
+        return written === buffer.length ? buffer : buffer.slice(0, written);
+    }
     const joined = new Uint8Array(total);
     let offset = 0;
     for (const chunk of chunks) {
@@ -303,10 +421,14 @@ async function fetchBytes(url, signal, maxBytes) {
 }
 function resolveMaxResponseBytes(opts) {
     const requested = opts?.maxResponseBytes;
-    if (typeof requested !== 'number' || !Number.isFinite(requested) || requested < 1) {
-        return DEFAULT_MAX_IPFS_RESPONSE_BYTES;
-    }
-    return Math.floor(requested);
+    if (typeof requested === 'number' && Number.isFinite(requested) && requested >= 1) {
+        return Math.floor(requested);
+    }
+    // The env replaces the default as the fallback; it is not a second
+    // validation layer, so an out-of-range *option* still falls through to it.
+    // `minimum = 1` is what keeps the cap from being disabled into an unbounded
+    // read: `0` and every other out-of-range value land on the default.
+    return envInteger('JINN_IPFS_MAX_RESPONSE_BYTES', DEFAULT_MAX_IPFS_RESPONSE_BYTES, 1);
 }
 function resolveFallbackGatewayBases(opts) {
     if (opts?.fallbackGatewayBase === false)
@@ -347,6 +469,24 @@ function resolveGatewayCandidateUrl(baseUrl, cidPath) {
     if (resolved.origin !== base.origin || !resolved.pathname.startsWith(base.pathname)) {
         return { reason: 'candidate URL escapes the gateway path prefix' };
     }
+    // `new URL(cidPath, base)` drops the base's query unconditionally, which
+    // strips the API key off every request to an authenticated gateway (#3452).
+    // Re-attach it *after* the guard, so a manifest-supplied CID path can never
+    // influence the check, and only when the base has one, so every query-free
+    // base issues a byte-identical request. The base wins over any query the CID
+    // path carries: two query strings cannot be merged unambiguously, and
+    // letting manifest text override an operator's gateway credentials is the
+    // wrong direction.
+    //
+    // Two known limits, both narrow and neither fixed here. A *relative*
+    // redirect `Location` is resolved with `new URL(location, current)`, which
+    // drops the query, so the key is not forwarded across such a hop — gateways
+    // that redirect path form to subdomain form send an absolute `Location`, and
+    // `assertRedirectAllowed` already pins the host family and port. And
+    // `displayUrl` stays `origin + pathname`, which is what keeps the credential
+    // out of logs now that the request actually carries it.
+    if (base.search !== '')
+        resolved.search = base.search;
     return { url: resolved };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinn-network/core",
-  "version": "0.1.2-canary.bebeb033",
+  "version": "0.1.2-canary.c8da24a8",
   "description": "Domain core for Jinn — evidence/contribution stores, scrub, trajectory parsing, and corpus reads. Independent of operator/src.",
   "type": "module",
   "packageManager": "yarn@4.13.0",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",
-    "@jinn-network/plugin": "0.1.2-canary.bebeb033",
+    "@jinn-network/plugin": "0.1.2-canary.c8da24a8",
     "@lmoe/gliner-onnx": "0.1.0",
     "@noble/hashes": "^2.2.0",
     "@secretlint/core": "^13.0.2",