@jinn-network/client 0.1.9 → 0.2.0

package/node_modules/@jinn-network/core/dist/execution-envelope.js

@@ -0,0 +1,203 @@
+/**
+ * jinn.execution.v1 — generic signed envelope.
+ *
+ * Scope: docs/superpowers/specs/2026-04-23-jinn-execution-envelope-tee-scope.md
+ * §3.1 (D5 + K1 knowledge tree), §3.2 (K3 executor provenance), §3.4 migration.
+ *
+ * One envelope shape covers solution manifests (role='solution') and
+ * verdict manifests (role='verdict'). Payload is typed per (solverType, role) via
+ * the registry in `./payloads/`.
+ */
+import { z } from 'zod/v3';
+import { WindowSchema } from './window.js';
+import { SessionProvenanceSchema } from './session-provenance.js';
+const HexStringSchema = z.string().regex(/^0x[0-9a-fA-F]*$/);
+export const EvidenceTierSchema = z.enum([
+    'self-signed',
+    'committed',
+    'attested',
+]);
+export const CanonicalRoleSchema = z.enum(['solution', 'verdict', 'capture']);
+export const RawRoleSchema = z.union([CanonicalRoleSchema, z.literal('restoration')]);
+export function normalizeEnvelopeRole(role) {
+    return role === 'restoration' ? 'solution' : role;
+}
+export const RoleSchema = z.preprocess(normalizeEnvelopeRole, CanonicalRoleSchema);
+export const GeneratorModelSchema = z.object({
+    id: z.string().min(1),
+    provider: z.string().optional(),
+    openWeights: z.boolean().optional(),
+    source: z.enum(['stream', 'config']),
+});
+export const DistributionClassSchema = z.enum(['open', 'restricted-tos', 'unknown']);
+const TaskProvenanceSchema = z.object({
+    cid: z.string().min(1),
+    onchainCreationTx: HexStringSchema,
+    onchainCreationBlock: z.number().int(),
+    requestId: HexStringSchema,
+    /**
+     * Unix-seconds timestamp of the on-chain creation block. Sourced from
+     * `publicClient.getBlock({ blockNumber })` at claim time (I2 freshness
+     * semantics, #1827). Absent when the RPC lookup failed — NEVER stamped
+     * with "now": a too-late guess would falsely claim post-cutoff freshness.
+     */
+    createdAt: z.number().int().optional(),
+    /**
+     * SWE-bench-style task identity, copied at assembly time from the parsed
+     * task document (`task.spec.instance_id` / `.repo` / `.base_commit`).
+     * Present for swe-rebench-v2.v1 / jinn-repo.v1 solver types; absent
+     * (correctly) for solver types without repo identity (e.g. prediction.*).
+     * Materializes the join key C11 (#1842) needs for F2P/P2P + base-commit
+     * resolution — #1827.
+     */
+    instanceId: z.string().optional(),
+    repo: z.string().optional(),
+    baseCommit: z.string().optional(),
+});
+const ParticipantSchema = z.object({
+    safeAddress: HexStringSchema,
+    agentEoa: HexStringSchema,
+});
+const SigningKeySchema = z.object({
+    kind: z.enum(['agent-eoa', 'enclave-bound']),
+    pubkey: HexStringSchema,
+});
+const SourceBundleSchema = z.object({
+    bundleCid: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    humanUrl: z.string().optional(),
+    buildRecipe: z.object({
+        kind: z.enum(['dockerfile', 'nix', 'bazel']),
+        path: z.string(),
+    }),
+    measurement: HexStringSchema,
+});
+const ExecutorSchema = z.object({
+    implName: z.string().min(1),
+    implVersion: z.string().min(1),
+    clientGitSha: z.string().min(1),
+    codeDigest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    runtimeBundleDigest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    plugins: z.array(z.object({
+        name: z.string().min(1),
+        version: z.string().min(1),
+        cid: z.string().min(1).optional(),
+        sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    })),
+    signingKey: SigningKeySchema,
+    source: SourceBundleSchema.optional(),
+    /**
+     * Harness execution mode. Optional in v1 envelope schema for back-compat with
+     * envelopes produced before this field was introduced. 'train' means the harness was running
+     * with state writes enabled (Improve + Memory phases active in
+     * claude-code-learner); 'frozen' means writes were disabled and the
+     * implStateDir hash was preserved across the Task. See
+     * docs/superpowers/specs/2026-05-06-agent-harness-solvernet-design.md §6.
+     *
+     * New envelopes always populate this field at assembly time. Readers should
+     * treat undefined as 'train' (the legacy behaviour).
+     */
+    mode: z.enum(['train', 'frozen']).optional(),
+    /**
+     * Underlying LLM model identifier this attempt was run against (e.g.
+     * 'claude-haiku-4-5-20251001', 'claude-sonnet-4-6', 'codex-defaults').
+     * Optional for back-compat: envelopes produced before this field was
+     * introduced lack it. Sourced from solverNet.model / claudeModel runtime
+     * config; stamped at envelope-assembly time. Indexer reads this for the
+     * network explorer's composition.byModel facet (jinn-mono-gbut, gh#191).
+     */
+    model: z.string().optional(),
+    /**
+     * Structured, stream-sourced model provenance (#1827). Distinct from the
+     * plain `model` string above: `source` is the honesty flag — 'stream'
+     * means harvested from the harness's own transcript (verifiable),
+     * 'config' means it fell back to solverNet/config declaration
+     * (unverified, but not fabricated). Optional for back-compat.
+     */
+    generatorModel: GeneratorModelSchema.optional(),
+});
+const AttestationSchema = z.object({
+    profile: z.string().min(1),
+    quote: z.string(),
+    reportData: HexStringSchema,
+    measurement: HexStringSchema,
+});
+export const ArtifactSourceSchema = z.object({
+    kind: z.literal('ipfs'),
+    cid: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    encoding: z.literal('jinn.artifact.donation.v1'),
+});
+const TrajectoryRefSchema = z.object({
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    access: z.object({
+        endpoint: z.string().url(),
+        priceUsdc: z.string().regex(/^\d+(\.\d+)?$/),
+    }),
+    sources: z.array(ArtifactSourceSchema).optional(),
+});
+const ArtifactSchema = z.object({
+    artifactType: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    metadata: z
+        .object({
+        description: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        producedBy: z
+            .object({
+            spanId: z.string(),
+            trajectoryCid: z.string(),
+        })
+            .optional(),
+    })
+        .optional(),
+    access: z.object({
+        endpoint: z.string().url(),
+        priceUsdc: z.string().regex(/^\d+(\.\d+)?$/),
+    }),
+    sources: z.array(ArtifactSourceSchema).optional(),
+});
+const SignatureSchema = z.object({
+    algo: z.literal('secp256k1'),
+    signer: HexStringSchema,
+    hash: HexStringSchema,
+    sig: HexStringSchema,
+});
+const BaseEnvelopeFields = {
+    schemaVersion: z.literal('jinn.execution.v1'),
+    solverType: z.string().min(1),
+    role: RoleSchema,
+    generatedAt: z.number().int(),
+    task: TaskProvenanceSchema.optional(),
+    sessionProvenance: SessionProvenanceSchema.optional(),
+    participant: ParticipantSchema,
+    window: WindowSchema,
+    executor: ExecutorSchema,
+    evidenceTier: EvidenceTierSchema,
+    /**
+     * Distribution/licensing class of the model that produced this record
+     * (#1827, §8.4). Derived at assembly time from `executor.generatorModel`
+     * — never caller-supplied, so it can't drift from the model that actually
+     * ran. 'unknown' when undeterminable; consumers MUST treat 'unknown' as
+     * 'restricted-tos' (never the reverse) and nothing defaults to 'open'.
+     */
+    distributionClass: DistributionClassSchema.optional(),
+    attestation: AttestationSchema.nullable(),
+    trajectory: TrajectoryRefSchema.nullable(),
+    artifacts: z.array(ArtifactSchema),
+    payload: z.record(z.unknown()),
+};
+export const UnsignedEnvelopeSchema = z
+    .object(BaseEnvelopeFields)
+    .refine((e) => e.evidenceTier !== 'attested' || e.executor.source !== undefined, { message: 'attested tier requires executor.source', path: ['executor', 'source'] })
+    .refine((e) => e.evidenceTier !== 'attested' || e.attestation !== null, { message: 'attested tier requires attestation', path: ['attestation'] })
+    .refine((e) => (e.role === 'capture'
+    ? e.sessionProvenance !== undefined && e.task === undefined
+    : e.task !== undefined && e.sessionProvenance === undefined), { message: 'role=capture requires sessionProvenance and no task; other roles require task and no sessionProvenance' });
+export const SignedEnvelopeSchema = z
+    .object({ ...BaseEnvelopeFields, role: RawRoleSchema, signature: SignatureSchema })
+    .refine((e) => e.evidenceTier !== 'attested' || e.executor.source !== undefined, { message: 'attested tier requires executor.source', path: ['executor', 'source'] })
+    .refine((e) => e.evidenceTier !== 'attested' || e.attestation !== null, { message: 'attested tier requires attestation', path: ['attestation'] })
+    .refine((e) => (e.role === 'capture'
+    ? e.sessionProvenance !== undefined && e.task === undefined
+    : e.task !== undefined && e.sessionProvenance === undefined), { message: 'role=capture requires sessionProvenance and no task; other roles require task and no sessionProvenance' });

package/node_modules/@jinn-network/core/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './contribution-store.js';
+export * from './evidence-adapter.js';
+export * from './captured-task.js';
+export * from './envelope.js';
+export * from './manifest.js';
+export * from './evidence-index.js';
+export * from './execution-envelope.js';
+export * from './skill-artifact.js';
+export * from './window.js';
+export * from './session-provenance.js';
+export * from './canonical-json.js';
+export * from './paired.js';

package/node_modules/@jinn-network/core/dist/index.js

@@ -0,0 +1,12 @@
+export * from './contribution-store.js';
+export * from './evidence-adapter.js';
+export * from './captured-task.js';
+export * from './envelope.js';
+export * from './manifest.js';
+export * from './evidence-index.js';
+export * from './execution-envelope.js';
+export * from './skill-artifact.js';
+export * from './window.js';
+export * from './session-provenance.js';
+export * from './canonical-json.js';
+export * from './paired.js';

package/node_modules/@jinn-network/core/dist/manifest.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Client-independent manifest commitment primitives.
+ *
+ * Both the ERC-8004 consumer and the harness-layer batch publisher use this
+ * module so the body schema and merkle construction cannot drift across the
+ * frozen package boundary.
+ */
+import { z } from 'zod';
+export type Hex = `0x${string}`;
+export declare const MANIFEST_SCHEMA_VERSION: "jinn.manifest.v0";
+export declare const ManifestMemberSchema: z.ZodObject<{
+    cid: z.ZodString;
+    sha256: z.ZodString;
+    polarity: z.ZodOptional<z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+    }>>;
+    instanceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ManifestV0Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"jinn.manifest.v0">;
+    batchKind: z.ZodString;
+    createdAt: z.ZodNumber;
+    merkleRoot: z.ZodString;
+    members: z.ZodArray<z.ZodObject<{
+        cid: z.ZodString;
+        sha256: z.ZodString;
+        polarity: z.ZodOptional<z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+        }>>;
+        instanceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ManifestMember = z.infer<typeof ManifestMemberSchema>;
+export type ManifestV0 = z.infer<typeof ManifestV0Schema>;
+export declare function parseManifestV0(input: unknown): ManifestV0;
+export interface MerkleProof {
+    index: number;
+    siblings: Hex[];
+}
+export declare function hashLeaf(cid: string): Hex;
+export declare function merkleRoot(leaves: Hex[]): Hex;
+export declare function merkleProof(leaves: Hex[], index: number): MerkleProof;
+export declare function verifyMerkleProof(leafCid: string, proof: MerkleProof, root: Hex): boolean;
+export declare const MANIFEST_PAYLOAD_TUPLE: readonly [{
+    readonly name: "version";
+    readonly type: "uint16";
+}, {
+    readonly name: "merkleRoot";
+    readonly type: "bytes32";
+}, {
+    readonly name: "memberCount";
+    readonly type: "uint32";
+}, {
+    readonly name: "createdAt";
+    readonly type: "uint64";
+}];
+export interface ManifestPayload {
+    version: 0;
+    merkleRoot: Hex;
+    memberCount: number;
+    createdAt: number;
+}
+export declare class ManifestPayloadValidationError extends Error {
+    constructor(reason: string);
+}
+export declare function validateManifestPayload(payload: ManifestPayload): ManifestPayload;
+export declare function encodeManifestPayload(payload: ManifestPayload): Hex;
+export declare function decodeManifestPayload(hex: Hex): ManifestPayload;
+export declare const MANIFEST_METADATA_KEY_PREFIX = "manifest:";
+export declare function buildManifestMetadataKey(manifestCid: string): string;
+export declare function parseManifestMetadataKey(key: string): {
+    manifestCid: string;
+} | null;

package/node_modules/@jinn-network/core/dist/manifest.js

@@ -0,0 +1,184 @@
+/**
+ * Client-independent manifest commitment primitives.
+ *
+ * Both the ERC-8004 consumer and the harness-layer batch publisher use this
+ * module so the body schema and merkle construction cannot drift across the
+ * frozen package boundary.
+ */
+import { z } from 'zod';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+export const MANIFEST_SCHEMA_VERSION = 'jinn.manifest.v0';
+const Bytes32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+const Sha256Schema = z.string().regex(/^[0-9a-f]{64}$/);
+export const ManifestMemberSchema = z.strictObject({
+    cid: z.string().min(1),
+    sha256: Sha256Schema,
+    polarity: z.enum(['pass', 'fail']).optional(),
+    instanceId: z.string().min(1).optional(),
+});
+export const ManifestV0Schema = z.strictObject({
+    schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
+    batchKind: z.string().min(1),
+    createdAt: z.number().int().nonnegative(),
+    merkleRoot: Bytes32Schema,
+    members: z.array(ManifestMemberSchema).min(1),
+});
+export function parseManifestV0(input) {
+    return ManifestV0Schema.parse(input);
+}
+export function hashLeaf(cid) {
+    return bytesToHex(keccak_256(new TextEncoder().encode(cid)));
+}
+function hashPair(left, right) {
+    const leftBytes = hexToBytes(left);
+    const rightBytes = hexToBytes(right);
+    const combined = new Uint8Array(leftBytes.length + rightBytes.length);
+    combined.set(leftBytes);
+    combined.set(rightBytes, leftBytes.length);
+    return bytesToHex(keccak_256(combined));
+}
+function bytesToHex(bytes) {
+    return `0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+function hexToBytes(hex) {
+    const raw = hex.slice(2);
+    if (raw.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(raw)) {
+        throw new Error('invalid hex');
+    }
+    return Uint8Array.from(raw.match(/.{2}/g)?.map((byte) => Number.parseInt(byte, 16)) ?? []);
+}
+export function merkleRoot(leaves) {
+    if (leaves.length === 0) {
+        throw new Error('merkleRoot: cannot build a tree over zero leaves (a batch must have ≥1 member)');
+    }
+    let level = leaves;
+    while (level.length > 1) {
+        const next = [];
+        for (let index = 0; index < level.length; index += 2) {
+            const left = level[index];
+            const right = index + 1 < level.length ? level[index + 1] : left;
+            next.push(hashPair(left, right));
+        }
+        level = next;
+    }
+    return level[0];
+}
+export function merkleProof(leaves, index) {
+    if (leaves.length === 0) {
+        throw new Error('merkleProof: cannot prove over zero leaves');
+    }
+    if (!Number.isInteger(index) || index < 0 || index >= leaves.length) {
+        throw new Error(`merkleProof: index ${index} out of range [0, ${leaves.length})`);
+    }
+    const siblings = [];
+    let level = leaves;
+    let currentIndex = index;
+    while (level.length > 1) {
+        const siblingIndex = currentIndex % 2 === 1 ? currentIndex - 1 : currentIndex + 1;
+        siblings.push(siblingIndex < level.length ? level[siblingIndex] : level[currentIndex]);
+        const next = [];
+        for (let levelIndex = 0; levelIndex < level.length; levelIndex += 2) {
+            const left = level[levelIndex];
+            const right = levelIndex + 1 < level.length ? level[levelIndex + 1] : left;
+            next.push(hashPair(left, right));
+        }
+        level = next;
+        currentIndex = Math.floor(currentIndex / 2);
+    }
+    return { index, siblings };
+}
+export function verifyMerkleProof(leafCid, proof, root) {
+    const isHash = (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value);
+    if (!Number.isSafeInteger(proof.index) ||
+        proof.index < 0 ||
+        !isHash(root) ||
+        !Array.isArray(proof.siblings) ||
+        !proof.siblings.every(isHash)) {
+        return false;
+    }
+    let node = hashLeaf(leafCid);
+    let currentIndex = proof.index;
+    for (const sibling of proof.siblings) {
+        node =
+            currentIndex % 2 === 1
+                ? hashPair(sibling, node)
+                : hashPair(node, sibling);
+        currentIndex = Math.floor(currentIndex / 2);
+    }
+    return currentIndex === 0 && node.toLowerCase() === root.toLowerCase();
+}
+export const MANIFEST_PAYLOAD_TUPLE = [
+    { name: 'version', type: 'uint16' },
+    { name: 'merkleRoot', type: 'bytes32' },
+    { name: 'memberCount', type: 'uint32' },
+    { name: 'createdAt', type: 'uint64' },
+];
+export class ManifestPayloadValidationError extends Error {
+    constructor(reason) {
+        super(`manifest payload validation failed: ${reason}`);
+        this.name = 'ManifestPayloadValidationError';
+    }
+}
+const MAX_UINT32 = 0xffff_ffff;
+const MAX_UINT64 = 0xffffffffffffffffn;
+const MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+export function validateManifestPayload(payload) {
+    if (payload.version !== 0) {
+        throw new ManifestPayloadValidationError(`version must be 0, got ${payload.version}`);
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(payload.merkleRoot)) {
+        throw new ManifestPayloadValidationError('merkleRoot must be 32-byte hex (0x + 64 hex chars)');
+    }
+    if (!Number.isInteger(payload.memberCount) || payload.memberCount < 1) {
+        throw new ManifestPayloadValidationError(`memberCount must be a positive integer (≥1); got ${payload.memberCount}`);
+    }
+    if (payload.memberCount > MAX_UINT32) {
+        throw new ManifestPayloadValidationError(`memberCount exceeds uint32 range; got ${payload.memberCount}`);
+    }
+    if (!Number.isSafeInteger(payload.createdAt) || payload.createdAt < 0) {
+        throw new ManifestPayloadValidationError(`createdAt must be a non-negative safe integer; got ${payload.createdAt}`);
+    }
+    if (BigInt(payload.createdAt) > MAX_UINT64) {
+        throw new ManifestPayloadValidationError(`createdAt exceeds uint64 range; got ${payload.createdAt}`);
+    }
+    return payload;
+}
+export function encodeManifestPayload(payload) {
+    validateManifestPayload(payload);
+    const word = (value) => value.toString(16).padStart(64, '0');
+    return `0x${word(BigInt(payload.version))}${payload.merkleRoot.slice(2)}${word(BigInt(payload.memberCount))}${word(BigInt(payload.createdAt))}`;
+}
+export function decodeManifestPayload(hex) {
+    if (!/^0x[0-9a-fA-F]{256}$/.test(hex)) {
+        throw new ManifestPayloadValidationError('encoded payload must be four 32-byte ABI words');
+    }
+    const raw = hex.slice(2);
+    const version = BigInt(`0x${raw.slice(0, 64)}`);
+    const merkleRoot = `0x${raw.slice(64, 128)}`;
+    const memberCount = BigInt(`0x${raw.slice(128, 192)}`);
+    const createdAt = BigInt(`0x${raw.slice(192, 256)}`);
+    if (createdAt > MAX_SAFE_INTEGER_BIGINT) {
+        throw new ManifestPayloadValidationError(`createdAt cannot be represented exactly as a JavaScript number; got ${createdAt}`);
+    }
+    return validateManifestPayload({
+        version: Number(version),
+        merkleRoot,
+        memberCount: Number(memberCount),
+        createdAt: Number(createdAt),
+    });
+}
+export const MANIFEST_METADATA_KEY_PREFIX = 'manifest:';
+export function buildManifestMetadataKey(manifestCid) {
+    if (typeof manifestCid !== 'string' || manifestCid.length === 0) {
+        throw new ManifestPayloadValidationError('manifestCid must be a non-empty string');
+    }
+    return `${MANIFEST_METADATA_KEY_PREFIX}${manifestCid}`;
+}
+export function parseManifestMetadataKey(key) {
+    if (typeof key !== 'string' ||
+        !key.startsWith(MANIFEST_METADATA_KEY_PREFIX)) {
+        return null;
+    }
+    const manifestCid = key.slice(MANIFEST_METADATA_KEY_PREFIX.length);
+    return manifestCid.length === 0 ? null : { manifestCid };
+}

package/node_modules/@jinn-network/core/dist/paired.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Paired (matched-design) comparison for the held-out exam.
+ *
+ * The exam scores the SAME slate against the before- and after-checkpoints, so
+ * the two result sets are MATCHED, not independent. The marginal test in
+ * `wilson.ts` (`compareRates`) compares two INDEPENDENT Wilson intervals and
+ * calls a delta trustworthy only when they are disjoint. On a matched design
+ * that is statistically wasteful: it carries the full between-instance
+ * difficulty variance ("this bug is just hard") in BOTH intervals, which swamps
+ * a real, consistent within-instance improvement. Example: a learner that flips
+ * 3 hard instances fail→pass and regresses none moves 4/10→7/10 — two Wilson
+ * intervals ([17,69]% vs [40,89]%) overlap → "within-noise", even though every
+ * observed change was an improvement.
+ *
+ * McNemar's test is the textbook test for matched binary data: it looks ONLY at
+ * the discordant pairs (instances that flipped) and asks whether the flips are
+ * asymmetric beyond chance. This is NOT a weaker bar — it is the CORRECT test
+ * for the design, and it still gates the claim on significance (exact two-sided
+ * p < alpha) AND on the improvement direction (more fail→pass than pass→fail).
+ * It is reported ALONGSIDE the conservative marginal verdict, never replacing it
+ * — so the exam is strengthened, never weakened (DR-2026-06-02-b §2a).
+ *
+ * R=1 (one run per instance) ships here: McNemar exact on per-instance flips.
+ * R>1 (per-instance pass RATES → Wilcoxon signed-rank / paired bootstrap) layers
+ * on once `eval_results` supports appended runs (DR-2026-06-02-b §2b).
+ */
+/** Minimal per-instance result (subset of PerTaskResult / EvalResultRow). */
+export interface PairedInput {
+    instance_id: string;
+    /** null when unscorable. */
+    passed: boolean | null;
+    unscorable: boolean;
+}
+export type PairedVerdict = 'trustworthy' | 'within-noise';
+export interface PairedComparison {
+    /** Instances scorable (passed !== null) in BOTH arms — the matched pairs. */
+    pairs: number;
+    /** b: before fail → after pass (improvements). */
+    improved: number;
+    /** c: before pass → after fail (regressions). */
+    regressed: number;
+    concordantPass: number;
+    concordantFail: number;
+    /** Instances unscorable/absent in either arm — excluded from the paired test. */
+    excluded: number;
+    /** Exact two-sided McNemar p-value over the discordant pairs. */
+    pValue: number;
+    /** 'trustworthy' iff pValue < alpha AND improved > regressed; else 'within-noise'. */
+    verdict: PairedVerdict;
+}
+/**
+ * Exact two-sided McNemar p-value for discordant counts `b` (improvements) and
+ * `c` (regressions). Under H0 each discordant pair is an independent fair coin,
+ * so the count of one direction is Binomial(n=b+c, 0.5); the two-sided p is
+ * `2 * P(X <= min(b,c))`, capped at 1. No `b==c==0` division (returns 1: no
+ * evidence). Computed iteratively (term ratio) so it is exact and overflow-free
+ * for any slate size.
+ */
+export declare function mcnemarExact(b: number, c: number): number;
+/**
+ * Paired McNemar comparison of two matched per-instance result sets. An instance
+ * contributes a pair ONLY when it is scorable (passed !== null, not unscorable)
+ * in BOTH arms — an unscorable/missing side is excluded (honest: a disk-skip or
+ * harness failure is never coerced into a flip). `alpha` defaults to 0.05.
+ */
+export declare function comparePaired(before: readonly PairedInput[], after: readonly PairedInput[], opts?: {
+    alpha?: number;
+}): PairedComparison;

package/node_modules/@jinn-network/core/dist/paired.js

@@ -0,0 +1,92 @@
+/**
+ * Paired (matched-design) comparison for the held-out exam.
+ *
+ * The exam scores the SAME slate against the before- and after-checkpoints, so
+ * the two result sets are MATCHED, not independent. The marginal test in
+ * `wilson.ts` (`compareRates`) compares two INDEPENDENT Wilson intervals and
+ * calls a delta trustworthy only when they are disjoint. On a matched design
+ * that is statistically wasteful: it carries the full between-instance
+ * difficulty variance ("this bug is just hard") in BOTH intervals, which swamps
+ * a real, consistent within-instance improvement. Example: a learner that flips
+ * 3 hard instances fail→pass and regresses none moves 4/10→7/10 — two Wilson
+ * intervals ([17,69]% vs [40,89]%) overlap → "within-noise", even though every
+ * observed change was an improvement.
+ *
+ * McNemar's test is the textbook test for matched binary data: it looks ONLY at
+ * the discordant pairs (instances that flipped) and asks whether the flips are
+ * asymmetric beyond chance. This is NOT a weaker bar — it is the CORRECT test
+ * for the design, and it still gates the claim on significance (exact two-sided
+ * p < alpha) AND on the improvement direction (more fail→pass than pass→fail).
+ * It is reported ALONGSIDE the conservative marginal verdict, never replacing it
+ * — so the exam is strengthened, never weakened (DR-2026-06-02-b §2a).
+ *
+ * R=1 (one run per instance) ships here: McNemar exact on per-instance flips.
+ * R>1 (per-instance pass RATES → Wilcoxon signed-rank / paired bootstrap) layers
+ * on once `eval_results` supports appended runs (DR-2026-06-02-b §2b).
+ */
+/**
+ * Exact two-sided McNemar p-value for discordant counts `b` (improvements) and
+ * `c` (regressions). Under H0 each discordant pair is an independent fair coin,
+ * so the count of one direction is Binomial(n=b+c, 0.5); the two-sided p is
+ * `2 * P(X <= min(b,c))`, capped at 1. No `b==c==0` division (returns 1: no
+ * evidence). Computed iteratively (term ratio) so it is exact and overflow-free
+ * for any slate size.
+ */
+export function mcnemarExact(b, c) {
+    const n = b + c;
+    if (n === 0)
+        return 1;
+    const k = Math.min(b, c);
+    // sum_{i=0}^{k} C(n,i) * 0.5^n, via prob_0 = 0.5^n, prob_i = prob_{i-1}*(n-i+1)/i.
+    let term = Math.pow(0.5, n); // i = 0
+    let cdf = term;
+    for (let i = 1; i <= k; i++) {
+        term = (term * (n - i + 1)) / i;
+        cdf += term;
+    }
+    return Math.min(1, 2 * cdf);
+}
+/**
+ * Paired McNemar comparison of two matched per-instance result sets. An instance
+ * contributes a pair ONLY when it is scorable (passed !== null, not unscorable)
+ * in BOTH arms — an unscorable/missing side is excluded (honest: a disk-skip or
+ * harness failure is never coerced into a flip). `alpha` defaults to 0.05.
+ */
+export function comparePaired(before, after, opts = {}) {
+    const alpha = opts.alpha ?? 0.05;
+    const scorable = (r) => !r.unscorable && r.passed !== null;
+    const beforeById = new Map(before.map((r) => [r.instance_id, r]));
+    let improved = 0;
+    let regressed = 0;
+    let concordantPass = 0;
+    let concordantFail = 0;
+    let pairs = 0;
+    let excluded = 0;
+    const seen = new Set();
+    for (const a of after) {
+        seen.add(a.instance_id);
+        const b = beforeById.get(a.instance_id);
+        if (!b || !scorable(b) || !scorable(a)) {
+            excluded++;
+            continue;
+        }
+        pairs++;
+        const wasPass = b.passed === true;
+        const nowPass = a.passed === true;
+        if (!wasPass && nowPass)
+            improved++;
+        else if (wasPass && !nowPass)
+            regressed++;
+        else if (wasPass && nowPass)
+            concordantPass++;
+        else
+            concordantFail++;
+    }
+    // before-only instances (absent from after) are excluded too.
+    for (const b of before)
+        if (!seen.has(b.instance_id))
+            excluded++;
+    const pValue = mcnemarExact(improved, regressed);
+    const verdict = pValue < alpha && improved > regressed ? 'trustworthy' : 'within-noise';
+    return { pairs, improved, regressed, concordantPass, concordantFail, excluded, pValue, verdict };
+}