@jinn-network/core 0.1.0

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

@@ -0,0 +1,5 @@
+export declare function normalizeIpfsGatewayBase(gatewayUrl: string): string;
+export declare function buildIpfsHexCidCandidatesFromPartialHex(hex: string): string[];
+export declare function buildIpfsFetchCidPathCandidates(cidOrPath: string): string[];
+/** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
+export declare function fetchFromIpfs(gatewayUrl: string, cid: string): Promise<unknown>;

package/dist/corpus-read/ipfs.js

@@ -0,0 +1,72 @@
+const IPFS_FETCH_TIMEOUT_MS = 15_000;
+const FALLBACK_IPFS_GATEWAY_BASE = 'https://ipfs.io/ipfs/';
+export function normalizeIpfsGatewayBase(gatewayUrl) {
+    let normalized = gatewayUrl.trim();
+    if (normalized === '')
+        normalized = 'https://gateway.autonolas.tech';
+    normalized = normalized.replace(/\/+$/, '');
+    if (!normalized.toLowerCase().endsWith('/ipfs'))
+        normalized = `${normalized}/ipfs`;
+    return `${normalized}/`;
+}
+export function buildIpfsHexCidCandidatesFromPartialHex(hex) {
+    const normalized = (hex.startsWith('0x') ? hex.slice(2) : hex).toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(normalized))
+        return [hex];
+    return [`f01551220${normalized}`, `f01701220${normalized}`];
+}
+export function buildIpfsFetchCidPathCandidates(cidOrPath) {
+    const value = cidOrPath.trim();
+    const lower = value.toLowerCase();
+    if (lower.startsWith('f01551220') && lower.length > 9) {
+        return buildIpfsHexCidCandidatesFromPartialHex(lower.slice(9));
+    }
+    if (lower.startsWith('f01701220') && lower.length > 9) {
+        return buildIpfsHexCidCandidatesFromPartialHex(lower.slice(9));
+    }
+    if (/^[0-9a-f]{64}$/i.test(value)) {
+        return buildIpfsHexCidCandidatesFromPartialHex(value);
+    }
+    return [value];
+}
+async function fetchJson(url, signal) {
+    const response = await fetch(url, { method: 'GET', signal });
+    if (!response.ok) {
+        throw new Error(`IPFS fetch failed: ${response.status} ${response.statusText} (${url.slice(0, 80)}…)`);
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json'))
+        return response.json();
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`IPFS response is not JSON (content-type: ${contentType || 'none'})`);
+    }
+}
+/** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
+export async function fetchFromIpfs(gatewayUrl, cid) {
+    const primary = normalizeIpfsGatewayBase(gatewayUrl);
+    const errors = [];
+    for (const cidPath of buildIpfsFetchCidPathCandidates(cid)) {
+        for (const [name, baseUrl] of [
+            ['primary', primary],
+            ['fallback', FALLBACK_IPFS_GATEWAY_BASE],
+        ]) {
+            const url = `${baseUrl}${cidPath}`;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), IPFS_FETCH_TIMEOUT_MS);
+            try {
+                return await fetchJson(url, controller.signal);
+            }
+            catch (error) {
+                errors.push(`${name}:${url.slice(0, 100)}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+    }
+    throw new Error(`IPFS JSON fetch failed after all candidates: ${errors.join(' | ')}`);
+}

package/dist/corpus-read/route-resolver.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default RouteResolver — uses the artifact's own access.endpoint directly.
+ *
+ * Phase A.1 doesn't ship a centralized resolver: every artifact descriptor in
+ * the manifest envelope already carries its own `access.endpoint`. The default
+ * resolver simply returns null so the acquire chain falls through to the free
+ * origin fetch using that endpoint.
+ *
+ * Future phases may introduce a real resolver (e.g. multi-mirror selection,
+ * DHT lookup, peer routing) by implementing the `RouteResolver` interface from
+ * `./types.js`.
+ *
+ * Spec: spec/2026-04-30-phase-a-umbrella.md §2.5.
+ */
+import type { RouteResolver } from './types.js';
+export declare const noopRouteResolver: RouteResolver;

package/dist/corpus-read/route-resolver.js

@@ -0,0 +1,19 @@
+/**
+ * Default RouteResolver — uses the artifact's own access.endpoint directly.
+ *
+ * Phase A.1 doesn't ship a centralized resolver: every artifact descriptor in
+ * the manifest envelope already carries its own `access.endpoint`. The default
+ * resolver simply returns null so the acquire chain falls through to the free
+ * origin fetch using that endpoint.
+ *
+ * Future phases may introduce a real resolver (e.g. multi-mirror selection,
+ * DHT lookup, peer routing) by implementing the `RouteResolver` interface from
+ * `./types.js`.
+ *
+ * Spec: spec/2026-04-30-phase-a-umbrella.md §2.5.
+ */
+export const noopRouteResolver = {
+    async resolve() {
+        return null;
+    },
+};

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

@@ -0,0 +1,177 @@
+import type { AcquireResult } from './fetch-artifact.js';
+export interface EnvelopeRef {
+    manifestCid: string;
+    manifestHash: string;
+    operator: {
+        agentId: string;
+        safeAddress: string;
+    };
+    evidenceTier: 'self-signed' | 'committed' | 'attested' | 'unknown';
+    publishedAt: number;
+}
+export interface CorpusQuery {
+    solverType?: string;
+    artifactType?: string;
+    taskCid?: string;
+    participant?: {
+        safeAddress?: string;
+    };
+    evidenceTier?: 'self-signed' | 'committed' | 'attested';
+    generatedAfter?: number;
+    generatedBefore?: number;
+    limit?: number;
+    manifestHash?: string;
+}
+export interface ArtifactSource {
+    kind: 'ipfs';
+    cid: string;
+    sha256: string;
+    encoding: 'jinn.artifact.donation.v1';
+}
+export interface CorpusManifestArtifact {
+    artifactType: string;
+    sha256: string;
+    access: {
+        endpoint: string;
+        priceUsdc: string;
+    };
+    sources?: ArtifactSource[];
+}
+/**
+ * The read-side projection core needs from a signed execution envelope.
+ * Client-owned validation supplies this shape through `parseEnvelope`; core
+ * deliberately has no dependency on daemon schemas.
+ */
+export interface CorpusManifest {
+    solverType: string;
+    role: string;
+    generatedAt: number;
+    task?: {
+        cid: string;
+        requestId: string;
+    };
+    participant: {
+        safeAddress: string;
+    };
+    artifacts: CorpusManifestArtifact[];
+}
+export interface ManifestPreview<TEnvelope extends CorpusManifest = CorpusManifest> {
+    ref: EnvelopeRef;
+    envelope: TEnvelope;
+}
+export interface ArtifactContent {
+    sha256: string;
+    bytes: Buffer;
+    artifactType: string;
+    source: 'cache' | 'self-store' | 'origin' | 'route-resolver' | 'ipfs';
+    paidAmountUsdc: string;
+    fetchedAt: string;
+    sourceOperator?: string;
+}
+export interface CorpusEnvelope<TEnvelope extends CorpusManifest = CorpusManifest> extends ManifestPreview<TEnvelope> {
+    artifactContents: Map<string, ArtifactContent>;
+}
+export interface RouteResolver {
+    resolve(req: {
+        sha256: string;
+        access: {
+            endpoint: string;
+            priceUsdc: string;
+        };
+        requesterSafe: string;
+    }): Promise<{
+        bytes: Buffer;
+        sourceOperator?: string;
+        pricePaidUsdc: string;
+    } | null>;
+}
+export interface NetworkArtifactRow {
+    sha256: string;
+    artifactType: string;
+    content: Buffer;
+    fetchedAt: string;
+    sourceOperator?: string | null;
+}
+export interface ServedArtifactRow {
+    artifactType: string;
+    envelopeCid: string | null;
+    content: Buffer;
+}
+export interface SaveNetworkArtifactInput {
+    sha256: string;
+    artifactType: string;
+    envelopeCid: string | null;
+    content: Buffer;
+    source: 'origin' | 'route-resolver' | 'self-store-mirror';
+    sourceOperator?: string | null;
+    sourceEndpoint?: string | null;
+    paidAmountUsdc: string;
+    fetchedAt: string;
+}
+/** SQLite ownership remains client-side until C4; core consumes this port. */
+export interface CorpusStorePort {
+    getNetworkArtifact(sha256: string): NetworkArtifactRow | null;
+    touchNetworkArtifactUsage(sha256: string, usedAt: string): void;
+    saveNetworkArtifact(input: SaveNetworkArtifactInput): void;
+    getServedArtifact(sha256: string): ServedArtifactRow | null;
+}
+/** Chain/indexer selection remains client-side; core only needs this read port. */
+export interface CorpusDiscoveryPort {
+    queryEnvelopes(query: CorpusQuery): Promise<EnvelopeRef[]>;
+}
+export interface CorpusOptions<TEnvelope extends CorpusManifest = CorpusManifest> {
+    ipfsGatewayUrl: string;
+    store: CorpusStorePort;
+    signer: {
+        privateKey: string;
+    };
+    selfSafeAddress: string;
+    routeResolver?: RouteResolver;
+    discovery?: CorpusDiscoveryPort;
+    legacyQuery?: (query: CorpusQuery) => Promise<EnvelopeRef[]>;
+    parseEnvelope(input: unknown): TEnvelope;
+}
+export interface CorpusDeps {
+    fetchFromIpfs?: (gatewayUrl: string, cid: string) => Promise<unknown>;
+    acquireFn?: (endpoint: string, sha256: string, privateKey?: string) => Promise<Buffer | null | AcquireResult>;
+}
+export interface ReadArgs<TEnvelope extends CorpusManifest = CorpusManifest> {
+    query: CorpusQuery;
+    select?: (manifests: ManifestPreview<TEnvelope>[]) => ManifestPreview<TEnvelope>[];
+}
+export interface Corpus<TEnvelope extends CorpusManifest = CorpusManifest> {
+    read(args: ReadArgs<TEnvelope>): Promise<CorpusEnvelope<TEnvelope>[]>;
+    query(query: CorpusQuery): Promise<EnvelopeRef[]>;
+    fetchManifest(ref: EnvelopeRef): Promise<ManifestPreview<TEnvelope>>;
+    acquire(manifest: ManifestPreview<TEnvelope>): Promise<CorpusEnvelope<TEnvelope>>;
+    acquireBySha256(sha256: string, access: {
+        endpoint: string;
+        priceUsdc: string;
+    }, hint?: {
+        artifactType?: string;
+        envelopeCid?: string;
+        sources?: ArtifactSource[];
+        ownerSafe?: string;
+    }): Promise<ArtifactContent>;
+}
+export declare class ManifestFetchError extends Error {
+    readonly manifestCid: string;
+    readonly cause?: unknown | undefined;
+    constructor(manifestCid: string, message: string, cause?: unknown | undefined);
+}
+export declare class AcquireError extends Error {
+    readonly sha256: string;
+    readonly cause?: unknown | undefined;
+    constructor(sha256: string, message: string, cause?: unknown | undefined);
+}
+export declare class HashMismatchError extends Error {
+    readonly sha256Expected: string;
+    readonly sha256Actual: string;
+    readonly source: string;
+    readonly sourceOperator?: string | undefined;
+    constructor(sha256Expected: string, sha256Actual: string, source: string, sourceOperator?: string | undefined);
+}
+export declare class DiscoveryUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}

package/dist/corpus-read/types.js

@@ -0,0 +1,42 @@
+export class ManifestFetchError extends Error {
+    manifestCid;
+    cause;
+    constructor(manifestCid, message, cause) {
+        super(`manifest ${manifestCid}: ${message}`);
+        this.manifestCid = manifestCid;
+        this.cause = cause;
+        this.name = 'ManifestFetchError';
+    }
+}
+export class AcquireError extends Error {
+    sha256;
+    cause;
+    constructor(sha256, message, cause) {
+        super(`acquire ${sha256}: ${message}`);
+        this.sha256 = sha256;
+        this.cause = cause;
+        this.name = 'AcquireError';
+    }
+}
+export class HashMismatchError extends Error {
+    sha256Expected;
+    sha256Actual;
+    source;
+    sourceOperator;
+    constructor(sha256Expected, sha256Actual, source, sourceOperator) {
+        super(`hash mismatch: expected ${sha256Expected}, got ${sha256Actual} from ${source}`);
+        this.sha256Expected = sha256Expected;
+        this.sha256Actual = sha256Actual;
+        this.source = source;
+        this.sourceOperator = sourceOperator;
+        this.name = 'HashMismatchError';
+    }
+}
+export class DiscoveryUnavailableError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'DiscoveryUnavailableError';
+    }
+}

package/dist/envelope.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Layer-1 trace envelope — `jinn.trace-envelope.v0`.
+ *
+ * The scrubbed evidence envelope a harness publishes to the corpus when a
+ * user completes (or fails) a task with contribution consent on. FROZEN at
+ * v0 operator sign-off (spec Q1) — changes after that are a spec amendment
+ * to `spec/2026-07-02-jinn-harness-network.md`.
+ *
+ * The schema is CLOSED (strict objects at every level): unknown fields are
+ * rejected so nothing can be smuggled into published traces, or silently
+ * depended on by consumers, without a spec amendment.
+ *
+ * Field-by-field rationale, reader map, and three validated examples:
+ * `packages/layer/docs/envelope-v0.md` (the examples in that
+ * doc are parsed against this schema in `test/envelope.test.ts`).
+ *
+ * Step shape mirrors the capture-span shape (`SpanRow`,
+ * `client/src/store/captures.ts`) minus session/trace IDs, which are hoisted
+ * to `session`.
+ *
+ * Plan: docs/superpowers/plans/2026-07-02-jinn-harness-network-v0-plan.md
+ * Task 2 (issue #1309).
+ */
+import { z } from 'zod';
+export declare const TRACE_ENVELOPE_SCHEMA_VERSION: "jinn.trace-envelope.v0";
+export declare const EVIDENCE_PROVENANCES: readonly ["contributed", "imported", "derived-from-history"];
+export declare const EvidenceProvenanceSchema: z.ZodEnum<{
+    contributed: "contributed";
+    imported: "imported";
+    "derived-from-history": "derived-from-history";
+}>;
+export type EvidenceProvenance = z.infer<typeof EvidenceProvenanceSchema>;
+/** Max steps per envelope — keeps envelopes anchorable and cheap to fetch. */
+export declare const MAX_STEPS = 512;
+/** Max serialised size of a single step's `attributes`, in bytes. */
+export declare const MAX_STEP_ATTRIBUTES_BYTES: number;
+/** Max freeform distribution tags per envelope. */
+export declare const MAX_DISTRIBUTION_TAGS = 16;
+/**
+ * Verifiability tiers, weakest → strongest (spec §5). The
+ * ContributionActivityChecker counts contributions against this ladder;
+ * layer-2 promotion reads it as the quality gate.
+ */
+export declare const VERIFIABILITY_TIERS: readonly ["user-accepted", "tests-passed", "evaluator-verified"];
+export declare const VerifiabilityTierSchema: z.ZodEnum<{
+    "user-accepted": "user-accepted";
+    "tests-passed": "tests-passed";
+    "evaluator-verified": "evaluator-verified";
+}>;
+export type VerifiabilityTier = z.infer<typeof VerifiabilityTierSchema>;
+export declare const OutcomeStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    abandoned: "abandoned";
+}>;
+export type OutcomeStatus = z.infer<typeof OutcomeStatusSchema>;
+/**
+ * One compressed trace step. Mirrors `SpanRow`
+ * (client/src/store/captures.ts): scrubbed `attributes` plus the
+ * `redactedKeys` receipt of what the scrub pipeline removed.
+ */
+export declare const TraceStepSchema: z.ZodObject<{
+    spanId: z.ZodString;
+    parentSpanId: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    startTimeUnixNano: z.ZodString;
+    endTimeUnixNano: z.ZodString;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    redactedKeys: z.ZodArray<z.ZodString>;
+    truncatedKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type TraceStep = z.infer<typeof TraceStepSchema>;
+export declare const TraceEnvelopeV0Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"jinn.trace-envelope.v0">;
+    session: z.ZodObject<{
+        sessionId: z.ZodString;
+        capturedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    task: z.ZodObject<{
+        summary: z.ZodString;
+        distributionTags: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    environment: z.ZodObject<{
+        harness: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        model: z.ZodString;
+        tools: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    steps: z.ZodArray<z.ZodObject<{
+        spanId: z.ZodString;
+        parentSpanId: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        startTimeUnixNano: z.ZodString;
+        endTimeUnixNano: z.ZodString;
+        attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        redactedKeys: z.ZodArray<z.ZodString>;
+        truncatedKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    outcome: z.ZodObject<{
+        status: z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            abandoned: "abandoned";
+        }>;
+        verifiabilityTier: z.ZodEnum<{
+            "user-accepted": "user-accepted";
+            "tests-passed": "tests-passed";
+            "evaluator-verified": "evaluator-verified";
+        }>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    cost: z.ZodObject<{
+        durationMs: z.ZodNumber;
+        tokens: z.ZodOptional<z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+        }, z.core.$strict>>;
+        usdEstimate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    consent: z.ZodObject<{
+        contributionConsent: z.ZodLiteral<true>;
+        scrubCompleted: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    provenance: z.ZodEnum<{
+        contributed: "contributed";
+        imported: "imported";
+        "derived-from-history": "derived-from-history";
+    }>;
+}, z.core.$strict>;
+export type TraceEnvelopeV0 = z.infer<typeof TraceEnvelopeV0Schema>;
+/** Parse an untrusted value as a TraceEnvelopeV0; throws ZodError on any deviation. */
+export declare function parseTraceEnvelopeV0(input: unknown): TraceEnvelopeV0;

package/dist/envelope.js

@@ -0,0 +1,162 @@
+/**
+ * Layer-1 trace envelope — `jinn.trace-envelope.v0`.
+ *
+ * The scrubbed evidence envelope a harness publishes to the corpus when a
+ * user completes (or fails) a task with contribution consent on. FROZEN at
+ * v0 operator sign-off (spec Q1) — changes after that are a spec amendment
+ * to `spec/2026-07-02-jinn-harness-network.md`.
+ *
+ * The schema is CLOSED (strict objects at every level): unknown fields are
+ * rejected so nothing can be smuggled into published traces, or silently
+ * depended on by consumers, without a spec amendment.
+ *
+ * Field-by-field rationale, reader map, and three validated examples:
+ * `packages/layer/docs/envelope-v0.md` (the examples in that
+ * doc are parsed against this schema in `test/envelope.test.ts`).
+ *
+ * Step shape mirrors the capture-span shape (`SpanRow`,
+ * `client/src/store/captures.ts`) minus session/trace IDs, which are hoisted
+ * to `session`.
+ *
+ * Plan: docs/superpowers/plans/2026-07-02-jinn-harness-network-v0-plan.md
+ * Task 2 (issue #1309).
+ */
+import { z } from 'zod';
+export const TRACE_ENVELOPE_SCHEMA_VERSION = 'jinn.trace-envelope.v0';
+export const EVIDENCE_PROVENANCES = [
+    'contributed',
+    'imported',
+    'derived-from-history',
+];
+export const EvidenceProvenanceSchema = z.enum(EVIDENCE_PROVENANCES);
+/** Max steps per envelope — keeps envelopes anchorable and cheap to fetch. */
+export const MAX_STEPS = 512;
+/** Max serialised size of a single step's `attributes`, in bytes. */
+export const MAX_STEP_ATTRIBUTES_BYTES = 16 * 1024;
+/** Max freeform distribution tags per envelope. */
+export const MAX_DISTRIBUTION_TAGS = 16;
+/**
+ * Verifiability tiers, weakest → strongest (spec §5). The
+ * ContributionActivityChecker counts contributions against this ladder;
+ * layer-2 promotion reads it as the quality gate.
+ */
+export const VERIFIABILITY_TIERS = [
+    'user-accepted',
+    'tests-passed',
+    'evaluator-verified',
+];
+export const VerifiabilityTierSchema = z.enum(VERIFIABILITY_TIERS);
+export const OutcomeStatusSchema = z.enum(['completed', 'failed', 'abandoned']);
+/** Unix-nanosecond timestamp string (OTel span convention). */
+const UnixNanoSchema = z.string().regex(/^\d+$/, 'unix-nanosecond digit string');
+/** Non-empty, no surrounding whitespace. */
+const TrimmedString = (max) => z.string().min(1).max(max).regex(/^\S(.*\S)?$/s, 'no surrounding whitespace');
+/**
+ * One compressed trace step. Mirrors `SpanRow`
+ * (client/src/store/captures.ts): scrubbed `attributes` plus the
+ * `redactedKeys` receipt of what the scrub pipeline removed.
+ */
+export const TraceStepSchema = z.strictObject({
+    spanId: z.string().min(1),
+    parentSpanId: z.string().min(1).nullable(),
+    name: z.string().min(1),
+    startTimeUnixNano: UnixNanoSchema,
+    endTimeUnixNano: UnixNanoSchema,
+    attributes: z.record(z.string(), z.unknown()).superRefine((attrs, ctx) => {
+        let serialised;
+        try {
+            serialised = JSON.stringify(attrs);
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', message: 'attributes must be JSON-serialisable' });
+            return;
+        }
+        const bytes = Buffer.byteLength(serialised, 'utf8');
+        if (bytes > MAX_STEP_ATTRIBUTES_BYTES) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `attributes serialise to ${bytes} bytes (max ${MAX_STEP_ATTRIBUTES_BYTES})`,
+            });
+        }
+    }),
+    redactedKeys: z.array(z.string().min(1)),
+    /**
+     * Which attribute keys the capture→envelope pipeline truncated to fit
+     * `MAX_STEP_ATTRIBUTES_BYTES` — the visible truncation receipt, sibling
+     * to `redactedKeys` (2026-07-02 schema review, Q4).
+     */
+    truncatedKeys: z.array(z.string().min(1)).optional(),
+});
+export const TraceEnvelopeV0Schema = z.strictObject({
+    /** Migration gate — v1 readers reject/route on this. */
+    schemaVersion: z.literal(TRACE_ENVELOPE_SCHEMA_VERSION),
+    /** Capture-session identity: ledger correlation + dedup. */
+    session: z.strictObject({
+        sessionId: z.string().min(1).max(128),
+        capturedAt: z.iso.datetime(),
+    }),
+    /** What the user was doing — the demand signal (spec §5). */
+    task: z.strictObject({
+        /** Scrubbed one-line descriptor of the task. */
+        summary: TrimmedString(500),
+        /**
+         * Freeform — no fixed taxonomy; clustering is inferred server-side.
+         * At least one tag: an untagged envelope is invisible to the signal.
+         */
+        distributionTags: z.array(TrimmedString(64)).min(1).max(MAX_DISTRIBUTION_TAGS),
+    }),
+    /** Config-diversity fingerprint (spec §5): harness, model, tools. */
+    environment: z.strictObject({
+        harness: z.strictObject({
+            name: z.string().min(1),
+            version: z.string().min(1),
+        }),
+        model: z.string().min(1),
+        /** Tool names only — never tool configs or arguments. */
+        tools: z.array(z.string().min(1).max(128)).max(64),
+    }),
+    /** The compressed trace body — the evidence itself. */
+    steps: z.array(TraceStepSchema).min(1).max(MAX_STEPS),
+    /** What happened, and how the status was established. */
+    outcome: z.strictObject({
+        status: OutcomeStatusSchema,
+        /**
+         * How the recorded status was established — the anti-farming line the
+         * activity checker counts against. Qualifies the status, so failed
+         * tasks carry a tier too.
+         */
+        verifiabilityTier: VerifiabilityTierSchema,
+        summary: TrimmedString(500).optional(),
+    }),
+    /** What the task cost to run — the §8 capability-gate metric. */
+    cost: z.strictObject({
+        durationMs: z.number().int().nonnegative(),
+        tokens: z.strictObject({
+            input: z.number().int().nonnegative(),
+            output: z.number().int().nonnegative(),
+        }).optional(),
+        /** Decimal string — money is never IEEE-754. An estimate, named as such. */
+        usdEstimate: z.string().regex(/^\d+(\.\d+)?$/).optional(),
+    }),
+    /**
+     * The publish gate (spec §5), fail-closed at the type level: both flags
+     * are literal `true`, so an envelope representing an unconsented or
+     * unscrubbed trace is not constructible.
+     */
+    consent: z.strictObject({
+        /** First-run consent given AND no per-task veto on this trace. */
+        contributionConsent: z.literal(true),
+        /** The mandatory scrub pipeline completed on this trace. */
+        scrubCompleted: z.literal(true),
+    }),
+    /**
+     * `contributed` = real user trace; `imported` = seed (spec §7);
+     * `derived-from-history` = a same-schema projection of immutable ledger
+     * history. The distribution signal excludes `imported`.
+     */
+    provenance: EvidenceProvenanceSchema,
+});
+/** Parse an untrusted value as a TraceEnvelopeV0; throws ZodError on any deviation. */
+export function parseTraceEnvelopeV0(input) {
+    return TraceEnvelopeV0Schema.parse(input);
+}

package/dist/evidence-adapter.d.ts

@@ -0,0 +1,26 @@
+import type { EvidencePort, EvidenceRetentionPolicy } from '@jinn-network/plugin';
+import { type EpisodeV1 } from '@jinn-network/plugin';
+import { type CapturedTask } from './captured-task.js';
+export declare function episodeFileName(id: string): string;
+export interface EvidenceAdapterDeps {
+    /** The one dir this store reads legacy captures from AND writes episodes to. */
+    capturesDir: string;
+    /** Retention policy surfaced by `retention()` and used as the up-map default. */
+    retention?: EvidenceRetentionPolicy;
+    /**
+     * Best-effort notification after a successful write and retention pass.
+     * Derived views may refresh here, but their failure never invalidates the
+     * canonical episode write.
+     */
+    onStoreChanged?: () => void | Promise<void>;
+}
+/**
+ * Up-map a legacy `CapturedTask` to a strict `EpisodeV1`. Fail-closed:
+ * `EpisodeV1Schema.parse` throws if the up-map is wrong.
+ *
+ * Field gaps `CapturedTask` leaves that this fills: each step's discriminated
+ * `kind`, `environment.skillsLoadout` (default `[]`), `retention.policy`
+ * (from the adapter's configured retention), and `episodeId` (the sessionId).
+ */
+export declare function capturedTaskToEpisode(task: CapturedTask, retention: EvidenceRetentionPolicy): EpisodeV1;
+export declare function createEvidenceAdapter(deps: EvidenceAdapterDeps): EvidencePort;