@jinn-network/core 0.1.2-canary.b9f63334 → 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,59 +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 { fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
-const DONATION_ARTIFACT_ENCODING = 'jinn.artifact.donation.v1';
-function sha256Hex(buf) {
-    return createHash('sha256').update(buf).digest('hex');
-}
-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');
+/**
+ * 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 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,
@@ -78,13 +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.
+        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()) {
@@ -95,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();
@@ -125,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({
@@ -158,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;
-        }
-        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);
+    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);
         }
+        // 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);
     }
-    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);
-    }
+    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,
+    };
+}