@jinn-network/client 0.1.2 → 0.1.3-canary.24b69ea4

package/dist/corpus/acquire.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-artifact resolution chain: cache → self-store → routeResolver → origin.
+ *
+ * Always hash-verifies before persisting to cache.
+ *
+ * Spec §2.3 step 4-6.
+ */
+import type { Store } from '../store/store.js';
+import { type AcquireWithPaymentResult } from '../x402/acquire.js';
+import type { ArtifactContent, RouteResolver } from './types.js';
+import type { ArtifactSource } from '../types/envelope.js';
+/**
+ * Origin acquire function. Historically returned `Buffer | null`; the new
+ * discriminated union lets callers distinguish not_found vs payment_failed
+ * vs network_error. We accept either shape so test fakes that still return
+ * `Buffer | null` keep working.
+ */
+type AcquireFnLegacy = (endpoint: string, sha256: string, privateKey: string) => Promise<Buffer | null>;
+type AcquireFnNew = (endpoint: string, sha256: string, privateKey: string) => Promise<AcquireWithPaymentResult>;
+type AcquireFn = AcquireFnLegacy | AcquireFnNew;
+type FetchFromIpfsFn = (gatewayUrl: string, cid: string) => Promise<unknown>;
+export interface AcquireArtifactArgs {
+    sha256: string;
+    artifactType: string;
+    access: {
+        endpoint: string;
+        priceUsdc: string;
+    };
+    store: Store;
+    selfSafeAddress: string;
+    privateKey: string;
+    routeResolver?: RouteResolver;
+    envelopeCid?: string;
+    sources?: ArtifactSource[];
+    ipfsGatewayUrl?: string;
+    /** Safe address that produced this artifact, when known (from envelope.participant). */
+    ownerSafe?: string;
+    acquireFn?: AcquireFn;
+    fetchFromIpfs?: FetchFromIpfsFn;
+}
+export declare function acquireArtifactContent(args: AcquireArtifactArgs): Promise<ArtifactContent>;
+export {};

package/dist/corpus/acquire.js

@@ -0,0 +1,213 @@
+/**
+ * Per-artifact resolution chain: cache → self-store → routeResolver → origin.
+ *
+ * Always hash-verifies before persisting to cache.
+ *
+ * Spec §2.3 step 4-6.
+ */
+import { createHash } from 'node:crypto';
+import { acquireArtifactWithPayment } from '../x402/acquire.js';
+import { AcquireError, HashMismatchError } from './types.js';
+import { fetchFromIpfs as defaultFetchFromIpfs } from '../adapters/mech/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');
+}
+export async function acquireArtifactContent(args) {
+    const { sha256, artifactType, access, store, selfSafeAddress, privateKey, routeResolver, envelopeCid, sources = [], ipfsGatewayUrl, ownerSafe, acquireFn = acquireArtifactWithPayment, fetchFromIpfs = defaultFetchFromIpfs, } = args;
+    const now = () => new Date().toISOString();
+    // 1. Cache hit
+    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,
+        };
+    }
+    // 2. Public IPFS donation source.
+    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 ts = now();
+            store.saveNetworkArtifact({
+                sha256,
+                artifactType,
+                envelopeCid: envelopeCid ?? null,
+                content: bytes,
+                source: 'origin',
+                sourceOperator: ownerSafe ?? null,
+                sourceEndpoint: `ipfs://${ipfsSource.cid}`,
+                paidAmountUsdc: '0',
+                fetchedAt: ts,
+            });
+            return {
+                sha256,
+                bytes,
+                artifactType,
+                source: 'ipfs',
+                paidAmountUsdc: '0',
+                fetchedAt: ts,
+                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 paid acquisition
+            // chain; only verified byte hash mismatches remain fatal.
+        }
+    }
+    // 3. Self-store fast path
+    if (ownerSafe && ownerSafe.toLowerCase() === selfSafeAddress.toLowerCase()) {
+        const own = store.getServedArtifact(sha256);
+        if (own) {
+            // Re-verify before mirroring. If served_artifacts has been corrupted
+            // (disk error, manual edit, future migration bug, etc.) we must NOT
+            // propagate the bad bytes into network_artifacts where peers can
+            // fetch them via x402. 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);
+            }
+            // Mirror into cache so peer asks for the same content can hit cache (provenance: self-store-mirror).
+            const ts = now();
+            store.saveNetworkArtifact({
+                sha256,
+                artifactType: own.artifactType,
+                envelopeCid: own.envelopeCid,
+                content: own.content,
+                source: 'self-store-mirror',
+                paidAmountUsdc: '0',
+                fetchedAt: ts,
+            });
+            return {
+                sha256,
+                bytes: own.content,
+                artifactType: own.artifactType,
+                source: 'self-store',
+                paidAmountUsdc: '0',
+                fetchedAt: ts,
+            };
+        }
+    }
+    // 4. Route resolver
+    if (routeResolver) {
+        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 ts = now();
+                store.saveNetworkArtifact({
+                    sha256,
+                    artifactType,
+                    envelopeCid: envelopeCid ?? null,
+                    content: out.bytes,
+                    source: 'route-resolver',
+                    sourceOperator: out.sourceOperator ?? null,
+                    paidAmountUsdc: out.pricePaidUsdc,
+                    fetchedAt: ts,
+                });
+                return {
+                    sha256,
+                    bytes: out.bytes,
+                    artifactType,
+                    source: 'route-resolver',
+                    paidAmountUsdc: out.pricePaidUsdc,
+                    fetchedAt: ts,
+                    sourceOperator: out.sourceOperator,
+                };
+            }
+        }
+        catch (err) {
+            if (err instanceof HashMismatchError)
+                throw err;
+            throw new AcquireError(sha256, 'routeResolver failed', err);
+        }
+    }
+    // 5. Origin fetch
+    let bytes;
+    try {
+        const raw = await acquireFn(access.endpoint, sha256, privateKey);
+        // Accept both the legacy `Buffer | null` shape and the new discriminated
+        // union from acquireArtifactWithPayment. 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);
+        }
+    }
+    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 / payment failed)');
+    }
+    const actualSha = sha256Hex(bytes);
+    if (actualSha !== sha256) {
+        throw new HashMismatchError(sha256, actualSha, 'origin', ownerSafe);
+    }
+    const ts = now();
+    store.saveNetworkArtifact({
+        sha256,
+        artifactType,
+        envelopeCid: envelopeCid ?? null,
+        content: bytes,
+        source: 'origin',
+        sourceOperator: ownerSafe ?? null,
+        sourceEndpoint: access.endpoint,
+        paidAmountUsdc: access.priceUsdc,
+        fetchedAt: ts,
+    });
+    return {
+        sha256,
+        bytes,
+        artifactType,
+        source: 'origin',
+        paidAmountUsdc: access.priceUsdc,
+        fetchedAt: ts,
+        sourceOperator: ownerSafe,
+    };
+}
+//# sourceMappingURL=acquire.js.map

package/dist/corpus/acquire.js.map

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

package/dist/corpus/cache.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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).
+ */
+import type { Store, NetworkArtifactRow } from '../store/store.js';
+export declare function getCachedArtifact(store: Store, sha256: string): NetworkArtifactRow | null;
+export declare function hasCachedArtifact(store: Store, sha256: string): boolean;

package/dist/corpus/cache.js

@@ -0,0 +1,18 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=cache.js.map

package/dist/corpus/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/corpus/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,UAAU,iBAAiB,CAAC,KAAY,EAAE,MAAc;IAC5D,OAAO,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAY,EAAE,MAAc;IAC5D,OAAO,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;AACnD,CAAC"}

package/dist/corpus/envelope-projection.d.ts

@@ -0,0 +1,12 @@
+import type { EnvelopeProjection, EnvelopeProjectionMetadata } from './types.js';
+import type { SignedEnvelope } from '../types/envelope.js';
+import type { Task } from '../types/task.js';
+export interface ProjectEnvelopeOptions {
+    envelopeCid?: string | null;
+    envelopeSha256?: string | null;
+    task?: Task | null;
+    taskCid?: string | null;
+    taskId?: string | null;
+    metadata?: EnvelopeProjectionMetadata;
+}
+export declare function projectEnvelope(envelope: SignedEnvelope, options?: ProjectEnvelopeOptions): EnvelopeProjection;

package/dist/corpus/envelope-projection.js

@@ -0,0 +1,110 @@
+const RESTORATION_TASK_CID_CONTEXT_KEY = 'restorationTaskCid';
+export function projectEnvelope(envelope, options = {}) {
+    const metadata = {};
+    setMetadata(metadata, 'participant.safeAddress', envelope.participant.safeAddress);
+    setMetadata(metadata, 'participant.agentEoa', envelope.participant.agentEoa);
+    setMetadata(metadata, 'executor.implName', envelope.executor.implName);
+    setMetadata(metadata, 'executor.implVersion', envelope.executor.implVersion);
+    setMetadata(metadata, 'executor.runtimeBundleDigest', envelope.executor.runtimeBundleDigest);
+    setMetadata(metadata, 'executor.plugins', JSON.stringify(envelope.executor.plugins.map((plugin) => ({
+        name: plugin.name,
+        version: plugin.version,
+        cid: plugin.cid ?? null,
+        sha256: plugin.sha256,
+    }))));
+    const projectedTaskCid = resolveProjectedTaskCid(envelope, options);
+    const projectedTaskId = options.taskId ?? options.task?.id ?? null;
+    setMetadata(metadata, 'taskCid', projectedTaskCid);
+    setMetadata(metadata, 'requestId', envelope.task?.requestId ?? null);
+    setMetadata(metadata, 'taskId', projectedTaskId);
+    if (envelope.solverType === 'prediction.v1') {
+        projectPredictionV1Fields(metadata, envelope, options.task);
+    }
+    for (const [key, value] of Object.entries(options.metadata ?? {})) {
+        setMetadata(metadata, key, value);
+    }
+    const solutionEnvelopeCid = stringFromMetadata(metadata, 'solutionEnvelope.cid');
+    const solutionEnvelopeSha256 = stringFromMetadata(metadata, 'solutionEnvelope.sha256');
+    const solutionEnvelopeRef = solutionEnvelopeCid
+        ?? solutionEnvelopeSha256
+        ?? (envelope.role === 'verdict' ? envelope.signature.hash : null);
+    const envelopeCid = options.envelopeCid ?? null;
+    const envelopeSha256 = options.envelopeSha256 ?? null;
+    const envelopeId = envelopeCid ?? envelopeSha256 ?? envelope.signature.hash;
+    return {
+        envelopeId,
+        envelopeCid,
+        envelopeSha256,
+        signatureHash: envelope.signature.hash,
+        solverType: envelope.solverType,
+        role: envelope.role,
+        taskCid: projectedTaskCid,
+        taskId: projectedTaskId,
+        requestId: envelope.task?.requestId ?? null,
+        generatedAt: envelope.generatedAt,
+        evidenceTier: envelope.evidenceTier,
+        participantSafeAddress: envelope.participant.safeAddress,
+        participantAgentEoa: envelope.participant.agentEoa,
+        executorImplName: envelope.executor.implName,
+        executorImplVersion: envelope.executor.implVersion,
+        executorRuntimeBundleDigest: envelope.executor.runtimeBundleDigest,
+        executorPlugins: envelope.executor.plugins.map((plugin) => plugin.name),
+        solutionEnvelopeCid,
+        solutionEnvelopeSha256,
+        solutionEnvelopeRef,
+        metadata,
+    };
+}
+function projectPredictionV1Fields(metadata, envelope, task) {
+    const taskSpec = record(task?.spec);
+    const taskSource = record(taskSpec?.source);
+    const taskIdentifiers = record(taskSource?.identifiers);
+    const taskQuestion = record(taskSpec?.question);
+    const payload = record(envelope.payload);
+    const resolutionSource = record(payload?.resolutionSource);
+    const payloadTask = record(payload?.task);
+    const scores = record(payload?.scores);
+    const solutionEnvelope = record(payload?.solutionEnvelope);
+    setMetadata(metadata, 'solverType', envelope.solverType);
+    setMetadata(metadata, 'role', envelope.role);
+    setMetadata(metadata, 'source.venue', stringValue(taskSource?.venue) ?? stringValue(resolutionSource?.venue));
+    setMetadata(metadata, 'source.marketId', stringValue(taskIdentifiers?.marketId) ?? stringValue(resolutionSource?.marketId));
+    setMetadata(metadata, 'source.conditionId', stringValue(taskIdentifiers?.conditionId) ?? stringValue(resolutionSource?.conditionId));
+    setMetadata(metadata, 'question.kind', stringValue(taskQuestion?.kind));
+    setMetadata(metadata, 'verdict', stringValue(payload?.verdict));
+    setMetadata(metadata, 'scores.solverBrier', stringValue(scores?.solverBrier));
+    setMetadata(metadata, 'scores.consensusBrier', stringValue(scores?.consensusBrier));
+    setMetadata(metadata, 'scores.brierSpread', stringValue(scores?.brierSpread));
+    setMetadata(metadata, 'solutionEnvelope.cid', stringValue(solutionEnvelope?.cid));
+    setMetadata(metadata, 'solutionEnvelope.sha256', stringValue(solutionEnvelope?.sha256));
+    setMetadata(metadata, 'payload.task.cid', stringValue(payloadTask?.cid));
+}
+function resolveProjectedTaskCid(envelope, options) {
+    if (options.taskCid)
+        return options.taskCid;
+    const contextTaskCid = options.task?.context?.[RESTORATION_TASK_CID_CONTEXT_KEY];
+    if (typeof contextTaskCid === 'string' && contextTaskCid.length > 0) {
+        return contextTaskCid;
+    }
+    const payloadTask = record(record(envelope.payload)?.task);
+    const payloadTaskCid = stringValue(payloadTask?.cid);
+    return payloadTaskCid ?? envelope.task?.cid ?? null;
+}
+function setMetadata(metadata, key, value) {
+    if (value === undefined || value === null)
+        return;
+    metadata[key] = value;
+}
+function stringFromMetadata(metadata, key) {
+    const value = metadata[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=envelope-projection.js.map

package/dist/corpus/envelope-projection.js.map

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

package/dist/corpus/fetch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fetch a manifest envelope from IPFS by CID and parse it under the v1 schema.
+ *
+ * Spec §2.3 step 2.
+ */
+import type { EnvelopeRef, ManifestPreview } from './types.js';
+type FetchFromIpfs = (gatewayUrl: string, cid: string) => Promise<unknown>;
+export declare function fetchManifest(ref: EnvelopeRef, ipfsGatewayUrl: string, fetchImpl?: FetchFromIpfs): Promise<ManifestPreview>;
+export {};

package/dist/corpus/fetch.js

@@ -0,0 +1,24 @@
+/**
+ * Fetch a manifest envelope from IPFS by CID and parse it under the v1 schema.
+ *
+ * Spec §2.3 step 2.
+ */
+import { SignedEnvelopeSchema } from '../types/envelope.js';
+import { fetchFromIpfs } from '../adapters/mech/ipfs.js';
+import { ManifestFetchError } from './types.js';
+export async function fetchManifest(ref, ipfsGatewayUrl, fetchImpl = fetchFromIpfs) {
+    let raw;
+    try {
+        raw = await fetchImpl(ipfsGatewayUrl, ref.manifestCid);
+    }
+    catch (err) {
+        throw new ManifestFetchError(ref.manifestCid, 'IPFS fetch failed', err);
+    }
+    const parsed = SignedEnvelopeSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new ManifestFetchError(ref.manifestCid, `schema parse failed: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+    }
+    const envelope = parsed.data;
+    return { ref, envelope };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/corpus/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/corpus/fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIhD,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAgB,EAChB,cAAsB,EACtB,YAA2B,aAAa;IAExC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,SAAS,CAAC,cAAc,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,kBAAkB,CAAC,GAAG,CAAC,WAAW,EAAE,mBAAmB,EAAE,GAAG,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,kBAAkB,CAC1B,GAAG,CAAC,WAAW,EACf,wBAAwB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzG,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAmB,MAAM,CAAC,IAAI,CAAC;IAC7C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC3B,CAAC"}

package/dist/corpus/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Corpus library entry point.
+ *
+ * Spec: spec/2026-04-30-phase-a-umbrella.md §2.
+ */
+import type { Corpus, CorpusOptions } from './types.js';
+export type { Corpus, CorpusOptions, CorpusQuery, EnvelopeRef, ManifestPreview, Envelope, ArtifactContent, ReadArgs, RouteResolver, } from './types.js';
+export { CorpusQueryError, ManifestFetchError, AcquireError, HashMismatchError } from './types.js';
+export { noopRouteResolver } from './route-resolver.js';
+export { getCachedArtifact, hasCachedArtifact } from './cache.js';
+export { queryScoreablePredictionBrierVerdicts, type ScoreablePredictionBrierVerdictQuery, } from './prediction-scoreable-verdicts.js';
+export { DEFAULT_PREDICTION_BRIER_SCOREBOARD_WINDOW_DAYS, aggregatePredictionBrierScoreboard, type PredictionBrierExclusionCounts, type PredictionBrierHarnessSummary, type PredictionBrierMetricSummary, type PredictionBrierOperatorSummary, type PredictionBrierOverallSummary, type PredictionBrierPluginSummary, type PredictionBrierScoreboard, type PredictionBrierScoreboardOptions, type PredictionBrierWeeklySummary, } from './prediction-brier-scoreboard.js';
+export { DEFAULT_PREDICTION_SCOREBOARD_REPORT_PATH, buildPredictionBrierScoreboard, queryPredictionBrierScoreboardProjections, renderPredictionBrierScoreboardMarkdown, type BuildPredictionBrierScoreboardOptions, type PredictionBrierScoreboardMarkdownOptions, type PredictionBrierScoreboardProjectionQuery, } from './prediction-brier-scoreboard-report.js';
+interface InternalDeps {
+    fetch?: typeof globalThis.fetch;
+    fetchFromIpfs?: (gatewayUrl: string, cid: string) => Promise<unknown>;
+    acquireFn?: (endpoint: string, sha256: string, privateKey: string) => Promise<Buffer | null>;
+}
+export declare function createCorpus(opts: CorpusOptions, deps?: InternalDeps): Corpus;

package/dist/corpus/index.js

@@ -0,0 +1,87 @@
+/**
+ * Corpus library entry point.
+ *
+ * Spec: spec/2026-04-30-phase-a-umbrella.md §2.
+ */
+import { runCorpusQuery } from './query.js';
+import { fetchManifest } from './fetch.js';
+import { acquireArtifactContent } from './acquire.js';
+export { CorpusQueryError, ManifestFetchError, AcquireError, HashMismatchError } from './types.js';
+export { noopRouteResolver } from './route-resolver.js';
+export { getCachedArtifact, hasCachedArtifact } from './cache.js';
+export { queryScoreablePredictionBrierVerdicts, } from './prediction-scoreable-verdicts.js';
+export { DEFAULT_PREDICTION_BRIER_SCOREBOARD_WINDOW_DAYS, aggregatePredictionBrierScoreboard, } from './prediction-brier-scoreboard.js';
+export { DEFAULT_PREDICTION_SCOREBOARD_REPORT_PATH, buildPredictionBrierScoreboard, queryPredictionBrierScoreboardProjections, renderPredictionBrierScoreboardMarkdown, } from './prediction-brier-scoreboard-report.js';
+export function createCorpus(opts, deps = {}) {
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const fetchFromIpfsImpl = deps.fetchFromIpfs;
+    const acquireFn = deps.acquireFn;
+    async function query(q) {
+        return runCorpusQuery(opts.subgraphUrl, q, fetchImpl);
+    }
+    async function fetchOne(ref) {
+        return fetchManifest(ref, opts.ipfsGatewayUrl, fetchFromIpfsImpl);
+    }
+    async function acquire(manifest) {
+        const contents = new Map();
+        for (const a of manifest.envelope.artifacts) {
+            const ac = await acquireArtifactContent({
+                sha256: a.sha256,
+                artifactType: a.artifactType,
+                access: a.access,
+                store: opts.store,
+                selfSafeAddress: opts.selfSafeAddress,
+                privateKey: opts.signer.privateKey,
+                routeResolver: opts.routeResolver,
+                envelopeCid: manifest.ref.manifestCid,
+                sources: a.sources,
+                ipfsGatewayUrl: opts.ipfsGatewayUrl,
+                ownerSafe: manifest.envelope.participant.safeAddress,
+                acquireFn,
+                fetchFromIpfs: fetchFromIpfsImpl,
+            });
+            contents.set(a.sha256, ac);
+        }
+        return { ref: manifest.ref, envelope: manifest.envelope, artifactContents: contents };
+    }
+    async function acquireBySha256(sha256, access, hint) {
+        return acquireArtifactContent({
+            sha256,
+            artifactType: hint?.artifactType ?? 'unknown',
+            access,
+            store: opts.store,
+            selfSafeAddress: opts.selfSafeAddress,
+            privateKey: opts.signer.privateKey,
+            routeResolver: opts.routeResolver,
+            envelopeCid: hint?.envelopeCid,
+            sources: hint?.sources,
+            ipfsGatewayUrl: opts.ipfsGatewayUrl,
+            acquireFn,
+            fetchFromIpfs: fetchFromIpfsImpl,
+        });
+    }
+    async function read(args) {
+        const refs = await query(args.query);
+        const previews = [];
+        for (const ref of refs) {
+            previews.push(await fetchOne(ref));
+        }
+        // Post-fetch solverType filter.
+        const kindFilter = args.query.solverType;
+        const kindFiltered = kindFilter ? previews.filter((p) => p.envelope.solverType === kindFilter) : previews;
+        const selected = args.select ? args.select(kindFiltered) : kindFiltered;
+        const envelopes = [];
+        for (const sel of selected) {
+            envelopes.push(await acquire(sel));
+        }
+        return envelopes;
+    }
+    return {
+        read,
+        query,
+        fetchManifest: fetchOne,
+        acquire,
+        acquireBySha256,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/corpus/index.js.map

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

package/dist/corpus/prediction-brier-scoreboard-report.d.ts

@@ -0,0 +1,17 @@
+import type { Store } from '../store/store.js';
+import type { EnvelopeProjection, EnvelopeProjectionQuery } from './types.js';
+import { type PredictionBrierScoreboard, type PredictionBrierScoreboardOptions } from './prediction-brier-scoreboard.js';
+export declare const DEFAULT_PREDICTION_SCOREBOARD_REPORT_PATH = "docs/superpowers/reports/prediction-solvernet-scoreboard.md";
+export interface PredictionBrierScoreboardProjectionQuery extends Pick<EnvelopeProjectionQuery, 'generatedAfter' | 'generatedBefore' | 'limit'> {
+}
+export interface BuildPredictionBrierScoreboardOptions extends PredictionBrierScoreboardOptions {
+    projectionQuery?: PredictionBrierScoreboardProjectionQuery;
+}
+export interface PredictionBrierScoreboardMarkdownOptions {
+    title?: string;
+    generatedAtIso?: string;
+    staleAfterDays?: number;
+}
+export declare function queryPredictionBrierScoreboardProjections(store: Pick<Store, 'queryEnvelopeProjections'>, query?: PredictionBrierScoreboardProjectionQuery): EnvelopeProjection[];
+export declare function buildPredictionBrierScoreboard(store: Pick<Store, 'queryEnvelopeProjections'>, options?: BuildPredictionBrierScoreboardOptions): PredictionBrierScoreboard;
+export declare function renderPredictionBrierScoreboardMarkdown(scoreboard: PredictionBrierScoreboard, options?: PredictionBrierScoreboardMarkdownOptions): string;