@jinn-network/jinn-layer 0.1.0

package/dist/cluster-selection.d.ts

@@ -0,0 +1,34 @@
+import type { DistillCluster } from './distill.js';
+export type ClusterSelectionTier = DistillCluster['tier'];
+export interface ClusterSelectionOptions {
+    maxClusters?: number;
+    maxContrastive?: number;
+    maxLessons?: number;
+    maxPatterns?: number;
+}
+export interface ClusterScore {
+    clusterId: string;
+    tier: ClusterSelectionTier;
+    score: number;
+    estimatedInputTokens: number;
+    groupSize: number;
+    nPass: number;
+    nFail: number;
+    reasons: string[];
+}
+export interface SelectedCluster {
+    cluster: DistillCluster;
+    score: ClusterScore;
+}
+export interface ClusterSelectionResult {
+    selected: SelectedCluster[];
+    rejected: Array<{
+        clusterId: string;
+        reason: string;
+        score: ClusterScore;
+    }>;
+    caps: Required<ClusterSelectionOptions>;
+}
+export declare function scoreCluster(cluster: DistillCluster): ClusterScore;
+export declare function resolveClusterSelectionCaps(opts?: ClusterSelectionOptions): Required<ClusterSelectionOptions>;
+export declare function selectUsefulClusters(clusters: DistillCluster[], opts?: ClusterSelectionOptions): ClusterSelectionResult;

package/dist/cluster-selection.js

@@ -0,0 +1,135 @@
+const DEFAULT_CAPS = {
+    maxContrastive: 8,
+    maxLessons: 6,
+    maxPatterns: 4,
+    maxClusters: 18,
+};
+const TIER_BASE = {
+    contrastive: 10_000,
+    lesson: 6_000,
+    pattern: 3_000,
+};
+function estimateTokens(value) {
+    return Math.ceil(Buffer.byteLength(JSON.stringify(value ?? ''), 'utf8') / 4);
+}
+function numberField(input, key) {
+    if (input && typeof input === 'object' && key in input) {
+        const value = input[key];
+        return typeof value === 'number' && Number.isFinite(value) ? value : null;
+    }
+    return null;
+}
+function inputItems(input) {
+    if (Array.isArray(input))
+        return input;
+    if (input && typeof input === 'object' && Array.isArray(input.items)) {
+        return input.items;
+    }
+    return [];
+}
+function outcomeStatus(item) {
+    if (!item || typeof item !== 'object')
+        return null;
+    const outcome = item.outcome;
+    if (!outcome || typeof outcome !== 'object')
+        return null;
+    const status = outcome.status;
+    return typeof status === 'string' ? status : null;
+}
+function clusterCounts(cluster) {
+    const items = inputItems(cluster.input);
+    const derivedPass = items.filter((item) => outcomeStatus(item) === 'completed').length;
+    const derivedFail = items.filter((item) => outcomeStatus(item) === 'failed').length;
+    const nPass = numberField(cluster.input, 'nPass') ?? derivedPass;
+    const nFail = numberField(cluster.input, 'nFail') ?? derivedFail;
+    const groupSize = numberField(cluster.input, 'groupSize') ?? Math.max(items.length, nPass + nFail, cluster.evidenceRefs.length);
+    return { groupSize, nPass, nFail };
+}
+export function scoreCluster(cluster) {
+    const { groupSize, nPass, nFail } = clusterCounts(cluster);
+    const estimatedInputTokens = estimateTokens(cluster.input);
+    const reasons = [cluster.tier];
+    let score = TIER_BASE[cluster.tier];
+    if (cluster.tier === 'contrastive') {
+        score += 1_500;
+        score += Math.min(nPass, nFail) * 250;
+        reasons.push('contrastive-pass-fail-delta');
+    }
+    if (cluster.tier === 'lesson') {
+        score += Math.min(nFail, 8) * 180;
+        if (nFail > 1)
+            reasons.push('high-attempt-lesson');
+    }
+    if (cluster.tier === 'pattern') {
+        score += Math.min(nPass, 8) * 120;
+        if (nPass > 1)
+            reasons.push('multi-attempt-pattern');
+    }
+    score += Math.min(groupSize, 8) * 80;
+    if (groupSize > 1)
+        reasons.push('multi-attempt');
+    const tokenPenalty = Math.ceil(estimatedInputTokens / 500);
+    score -= tokenPenalty;
+    if (tokenPenalty > 0)
+        reasons.push('token-penalty');
+    return {
+        clusterId: cluster.clusterId,
+        tier: cluster.tier,
+        score,
+        estimatedInputTokens,
+        groupSize,
+        nPass,
+        nFail,
+        reasons,
+    };
+}
+export function resolveClusterSelectionCaps(opts = {}) {
+    return {
+        maxContrastive: opts.maxContrastive ?? DEFAULT_CAPS.maxContrastive,
+        maxLessons: opts.maxLessons ?? DEFAULT_CAPS.maxLessons,
+        maxPatterns: opts.maxPatterns ?? DEFAULT_CAPS.maxPatterns,
+        maxClusters: opts.maxClusters ?? DEFAULT_CAPS.maxClusters,
+    };
+}
+export function selectUsefulClusters(clusters, opts = {}) {
+    const caps = resolveClusterSelectionCaps(opts);
+    const ranked = clusters
+        .map((cluster) => ({ cluster, score: scoreCluster(cluster) }))
+        .sort((a, b) => {
+        if (b.score.score !== a.score.score)
+            return b.score.score - a.score.score;
+        return a.cluster.clusterId.localeCompare(b.cluster.clusterId);
+    });
+    let contrastive = 0;
+    let lessons = 0;
+    let patterns = 0;
+    const selected = [];
+    const rejected = [];
+    for (const row of ranked) {
+        if (selected.length >= caps.maxClusters) {
+            rejected.push({ clusterId: row.cluster.clusterId, reason: 'total-cap', score: row.score });
+            continue;
+        }
+        if (row.cluster.tier === 'contrastive' && contrastive >= caps.maxContrastive) {
+            rejected.push({ clusterId: row.cluster.clusterId, reason: 'contrastive-cap', score: row.score });
+            continue;
+        }
+        if (row.cluster.tier === 'lesson' && lessons >= caps.maxLessons) {
+            rejected.push({ clusterId: row.cluster.clusterId, reason: 'lesson-cap', score: row.score });
+            continue;
+        }
+        if (row.cluster.tier === 'pattern' && patterns >= caps.maxPatterns) {
+            rejected.push({ clusterId: row.cluster.clusterId, reason: 'pattern-cap', score: row.score });
+            continue;
+        }
+        selected.push(row);
+        if (row.cluster.tier === 'contrastive')
+            contrastive += 1;
+        else if (row.cluster.tier === 'lesson')
+            lessons += 1;
+        else
+            patterns += 1;
+    }
+    selected.sort((a, b) => a.cluster.clusterId.localeCompare(b.cluster.clusterId));
+    return { selected, rejected, caps };
+}

package/dist/cluster.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The clustering step — group gate-eligible layer-1 evidence into
+ * `DistillCluster[]` for the distiller (spec/2026-07-06-distillation-v1.md §7).
+ *
+ * v1 clustering is deliberately simple: run each item through the promotion
+ * gate (`evaluateEligibility`, §6), drop ineligible evidence, then group the
+ * survivors by `(tier, instanceId)` — one cluster per distinct instance id per
+ * tier. A `pattern` and a `lesson` for the same instance are SEPARATE clusters
+ * (distinct-instance clustering; recursion/hierarchy are v3). Pure and
+ * deterministic: clusters come back sorted by `clusterId`.
+ */
+import type { DistillCluster, SkillKind } from './distill.js';
+import type { SkillPackage } from './skill-package.js';
+import type { TraceEnvelopeV0 } from './envelope.js';
+export interface ClusterItem {
+    /** Source evidence envelope ref → `metadata.jinn.provenance`. */
+    ref: string;
+    /** The SWE-bench-style instance id this evidence belongs to. */
+    instanceId: string;
+    /** Lineage equivalence key — echo instances collapse to source (§7). */
+    lineageKey?: string;
+    /** The scrubbed layer-1 trace envelope. */
+    env: TraceEnvelopeV0;
+}
+export interface ClusterOptions {
+    /** Held-out cap-v0 slate predicate — an item's instance in the slate is dropped. */
+    heldOut?: (instanceId: string) => boolean;
+    /** Overrides the gate's placeholder-density defacement threshold (§6). */
+    maxPlaceholderDensity?: number;
+    /**
+     * `network-strict` preserves the evaluator-verified promotion gate. The
+     * local experimental path may draft private skills from user-accepted traces,
+     * but those are not publishable network evidence.
+     */
+    eligibilityMode?: 'network-strict' | 'local-experimental';
+}
+/**
+ * Group eligible layer-1 evidence into distill clusters. Ineligible items (per
+ * the gate) are dropped. An instance with a single polarity yields one
+ * `pattern:`/`lesson:` cluster; an instance carrying BOTH an
+ * (eligible) pattern and lesson folds into ONE `contrastive:` cluster whose
+ * evidence refs link both polarities, and the singles are suppressed (§7 v0.5,
+ * ExpeL). The returned clusters are sorted by `clusterId` for determinism.
+ */
+export declare function clusterEvidence(items: ClusterItem[], opts?: ClusterOptions): DistillCluster[];
+/**
+ * A stage-1 published skill joined to its originating cluster's provenance —
+ * the stage-2 (cross-instance meta-distill) input (issue #1463). `pkg` supplies
+ * the meta-distiller's reading material (the distilled skill); `evidenceRefs` /
+ * `instanceIds` supply the union provenance and the ≥2-distinct-instance test.
+ */
+export interface Stage1PublishedSkill {
+    clusterId: string;
+    skillKind: SkillKind;
+    pkg: SkillPackage;
+    evidenceRefs: string[];
+    instanceIds: string[];
+    lineageKeys?: string[];
+}
+/** One labelled source inside a meta-cluster (its id is what the model echoes in `supports`). */
+export interface MetaSource {
+    id: string;
+    name: string;
+    description: string;
+    body: string;
+    evidenceRefs: string[];
+    instanceIds: string[];
+}
+/**
+ * The three stage-1 polarities eligible for stage-2 — `cross-instance` is
+ * excluded (no meta-of-meta), so it is deliberately absent from this union.
+ */
+export type MetaPolarity = 'strategic-pattern' | 'failure-lesson' | 'contrastive';
+/** A same-polarity batch of ≥2-distinct-instance stage-1 skills for the meta-distiller. */
+export interface MetaCluster {
+    metaClusterId: string;
+    polarity: MetaPolarity;
+    gateTier: DistillCluster['tier'];
+    sources: MetaSource[];
+}
+export declare function lineageEquivalenceKey(item: ClusterItem): string;
+/**
+ * Group stage-1 published skills into one meta-cluster per polarity. A polarity
+ * is meta-distillable only when it spans **≥2 distinct instances** (a
+ * cross-instance rule needs corroboration from different problems). Meta-of-meta
+ * is impossible: a `cross-instance` polarity is skipped. Deterministic —
+ * meta-clusters and their sources come back in a stable order.
+ */
+export declare function buildMetaClusters(published: Stage1PublishedSkill[]): MetaCluster[];

package/dist/cluster.js

@@ -0,0 +1,142 @@
+/**
+ * The clustering step — group gate-eligible layer-1 evidence into
+ * `DistillCluster[]` for the distiller (spec/2026-07-06-distillation-v1.md §7).
+ *
+ * v1 clustering is deliberately simple: run each item through the promotion
+ * gate (`evaluateEligibility`, §6), drop ineligible evidence, then group the
+ * survivors by `(tier, instanceId)` — one cluster per distinct instance id per
+ * tier. A `pattern` and a `lesson` for the same instance are SEPARATE clusters
+ * (distinct-instance clustering; recursion/hierarchy are v3). Pure and
+ * deterministic: clusters come back sorted by `clusterId`.
+ */
+import { evaluateEligibility } from './gate.js';
+function projectInput(items) {
+    return items.map((it) => ({
+        ref: it.ref,
+        instanceId: it.instanceId,
+        taskSummary: it.env.task.summary,
+        distributionTags: it.env.task.distributionTags,
+        outcome: { status: it.env.outcome.status, summary: it.env.outcome.summary },
+        steps: it.env.steps.map((s) => ({ name: s.name, attributes: s.attributes })),
+    }));
+}
+function buildCluster(clusterId, tier, instanceId, pass, fail) {
+    const items = [...pass, ...fail];
+    return {
+        clusterId,
+        tier,
+        evidenceRefs: items.map((it) => it.ref),
+        instanceIds: [instanceId],
+        // The distiller reads group-relative signal off the pass/fail split; carry
+        // it EXPLICITLY (§7, #1478) rather than making the model re-derive it from
+        // per-item outcomes. `items` is the flat projection (pass then fail).
+        input: {
+            instanceId,
+            tier,
+            groupSize: items.length,
+            nPass: pass.length,
+            nFail: fail.length,
+            items: projectInput(items),
+        },
+    };
+}
+/**
+ * Group eligible layer-1 evidence into distill clusters. Ineligible items (per
+ * the gate) are dropped. An instance with a single polarity yields one
+ * `pattern:`/`lesson:` cluster; an instance carrying BOTH an
+ * (eligible) pattern and lesson folds into ONE `contrastive:` cluster whose
+ * evidence refs link both polarities, and the singles are suppressed (§7 v0.5,
+ * ExpeL). The returned clusters are sorted by `clusterId` for determinism.
+ */
+export function clusterEvidence(items, opts = {}) {
+    // Bucket eligible items by (instanceId → polarity), preserving input order.
+    const byInstance = new Map();
+    let order = 0;
+    for (const item of items) {
+        const heldOut = opts.heldOut?.(item.instanceId) ?? false;
+        const result = evaluateEligibility(item.env, {
+            heldOut,
+            maxPlaceholderDensity: opts.maxPlaceholderDensity,
+            acceptUserAccepted: opts.eligibilityMode === 'local-experimental',
+        });
+        const tier = result.eligible ? result.tier : null;
+        if (tier === null)
+            continue;
+        let slot = byInstance.get(item.instanceId);
+        if (!slot) {
+            slot = { pattern: [], lesson: [], order: order++ };
+            byInstance.set(item.instanceId, slot);
+        }
+        slot[tier].push(item);
+    }
+    const clusters = [];
+    for (const [instanceId, slot] of byInstance) {
+        const hasPattern = slot.pattern.length > 0;
+        const hasLesson = slot.lesson.length > 0;
+        if (hasPattern && hasLesson) {
+            // Precedence: the contrastive fold SUPPRESSES the pattern-only/lesson-only
+            // singles. Pattern refs precede lesson refs in the merged provenance.
+            clusters.push(buildCluster(`contrastive:${instanceId}`, 'contrastive', instanceId, slot.pattern, slot.lesson));
+        }
+        else if (hasPattern) {
+            clusters.push(buildCluster(`pattern:${instanceId}`, 'pattern', instanceId, slot.pattern, []));
+        }
+        else if (hasLesson) {
+            clusters.push(buildCluster(`lesson:${instanceId}`, 'lesson', instanceId, [], slot.lesson));
+        }
+    }
+    clusters.sort((a, b) => (a.clusterId < b.clusterId ? -1 : a.clusterId > b.clusterId ? 1 : 0));
+    return clusters;
+}
+/** The structural-gate tier each meta-eligible polarity keeps in stage-2. */
+const META_GATE_TIER = {
+    'strategic-pattern': 'pattern',
+    'failure-lesson': 'lesson',
+    'contrastive': 'contrastive',
+};
+/** Meta-eligible polarity guard — the type-level "never recurse on cross-instance" gate. */
+function isMetaPolarity(kind) {
+    return kind in META_GATE_TIER;
+}
+export function lineageEquivalenceKey(item) {
+    return item.lineageKey ?? item.instanceId;
+}
+/**
+ * Group stage-1 published skills into one meta-cluster per polarity. A polarity
+ * is meta-distillable only when it spans **≥2 distinct instances** (a
+ * cross-instance rule needs corroboration from different problems). Meta-of-meta
+ * is impossible: a `cross-instance` polarity is skipped. Deterministic —
+ * meta-clusters and their sources come back in a stable order.
+ */
+export function buildMetaClusters(published) {
+    const byPolarity = new Map();
+    for (const p of published) {
+        if (!isMetaPolarity(p.skillKind))
+            continue; // never recurse on cross-instance
+        const group = byPolarity.get(p.skillKind) ?? [];
+        group.push(p);
+        byPolarity.set(p.skillKind, group);
+    }
+    const clusters = [];
+    for (const [polarity, group] of byPolarity) {
+        const distinctInstances = new Set(group.flatMap((g, gi) => g.instanceIds.map((id, ii) => g.lineageKeys?.[ii] ?? id)));
+        if (distinctInstances.size < 2)
+            continue;
+        const sources = group.map((g, i) => ({
+            id: `s${i + 1}`,
+            name: g.pkg.name,
+            description: g.pkg.description,
+            body: g.pkg.body,
+            evidenceRefs: g.evidenceRefs,
+            instanceIds: g.instanceIds,
+        }));
+        clusters.push({
+            metaClusterId: `cross-instance:${polarity}`,
+            polarity,
+            gateTier: META_GATE_TIER[polarity],
+            sources,
+        });
+    }
+    clusters.sort((a, b) => (a.metaClusterId < b.metaClusterId ? -1 : a.metaClusterId > b.metaClusterId ? 1 : 0));
+    return clusters;
+}

package/dist/consume.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Harness-layer consume path — the embeddable corpus surface.
+ *
+ * Thin wrapper over core's `createCorpus()` and the configured corpus
+ * discovery port. No new query logic lives
+ * here: `search` delegates ref discovery to the discovery port and manifest
+ * retrieval to the corpus, then applies a client-side substring match
+ * (solverType lives in the IPFS manifest body, not in the on-chain envelope
+ * payload, so the indexer cannot filter on it — see
+ * core's HTTP discovery `queryEnvelopes`). `get` is
+ * fetchManifest + acquire.
+ *
+ * Plan: docs/superpowers/plans/2026-07-02-jinn-harness-network-v0-plan.md
+ * Task 1 (issue #1308).
+ */
+import { type AcquireResult, type ArtifactContent, type CorpusDiscoveryPort, type CorpusStorePort, type EnvelopeRef } from '@jinn-network/core/corpus-read';
+import { type SignedEnvelope } from '@jinn-network/core';
+export declare const DEFAULT_TESTNET_DISCOVERY_URL = "https://jinn-indexer-production.up.railway.app";
+/**
+ * Default public IPFS gateway. Mirrors the `ipfsGatewayUrl` zod default in
+ * client/src/config.ts (inline schema default; not exported as a constant).
+ */
+export declare const DEFAULT_IPFS_GATEWAY_URL = "https://gateway.autonolas.tech";
+export interface HarnessLayerConfig {
+    /** Discovery indexer URL. Default: the testnet Ponder indexer. */
+    discoveryUrl?: string;
+    /** IPFS gateway for manifest / donated-artifact fetches. */
+    ipfsGatewayUrl?: string;
+    /** SQLite path for the artifact cache. Default: ~/.jinn-client/harness-layer/corpus-cache.db */
+    dbPath?: string;
+    /**
+     * Capture-meta search endpoint (#1344) — the content-aware fast path.
+     * Default: `<discoveryUrl base>/capture-meta` (the indexer serves it next
+     * to /graphql). Set to '' to disable.
+     */
+    captureMetaUrl?: string;
+    /** Injectable HTTP fetch for the capture-meta fast path (tests). */
+    fetchImpl?: typeof fetch;
+    /** Injectable DiscoveryAPI (tests). Overrides discoveryUrl. */
+    discovery?: CorpusDiscoveryPort;
+    /** Injectable core read-side store (tests/embedders). Overrides dbPath. */
+    store?: CorpusStorePort & {
+        path?: string;
+    };
+    /** Injectable IPFS fetch (tests). */
+    fetchFromIpfs?: (gatewayUrl: string, cid: string) => Promise<unknown>;
+    /** Injectable origin acquire fn (tests). */
+    acquireFn?: (endpoint: string, sha256: string, privateKey?: string) => Promise<Buffer | null | AcquireResult>;
+}
+export interface ResolvedHarnessLayerConfig {
+    discoveryUrl: string;
+    ipfsGatewayUrl: string;
+    dbPath: string;
+    /** '' when the content-aware fast path is disabled. */
+    captureMetaUrl: string;
+}
+/** One search result — a corpus record ref plus its provenance fields. */
+export interface CorpusSearchHit {
+    /** Human-readable title: `<solverType> / <role>`. */
+    title: string;
+    /** Record ref (the envelope manifest CID) — pass to `get()`. */
+    ref: string;
+    solverType: string;
+    role: string;
+    artifactTypes: string[];
+    /**
+     * `'skill'` when the record carries a `jinn.skill.v1` artifact, else
+     * `'trace'`. Note: legacy pre-#1394 seeded-trace records (skill.md as a step
+     * attribute, no first-class artifact) classify as `'trace'` here even though
+     * `extractSkill()` still recognises them via its fallback shape — acceptable
+     * because the layer-2 re-import supersedes them with first-class records.
+     */
+    kind: 'skill' | 'trace';
+    evidenceTier: EnvelopeRef['evidenceTier'];
+    generatedAt: number;
+    publishedAt: number;
+    operator: {
+        agentId: string;
+        safeAddress: string;
+    };
+    task: {
+        cid: string;
+        requestId: string;
+    } | null;
+    /** Distribution tags, when the hit came via the capture-meta fast path. */
+    tags?: string[];
+    /** Scrubbed task summary, when the hit came via the capture-meta fast path. */
+    summary?: string;
+    /** Repository identity from indexed canonical capture metadata. */
+    repositorySlug?: string;
+    /** Authored outcome/seed synthesis from indexed canonical capture metadata. */
+    synthesis?: string;
+    /** Named W2 allowlist decision; absent on legacy index rows. */
+    retrievalVisible?: boolean;
+}
+export interface CorpusArtifact {
+    sha256: string;
+    artifactType: string;
+    content: Buffer;
+    source: ArtifactContent['source'];
+    sizeBytes: number;
+}
+/** A fully-fetched corpus record: the signed envelope plus artifact bytes. */
+export interface CorpusRecord {
+    ref: string;
+    envelope: SignedEnvelope;
+    provenance: {
+        operator: {
+            agentId: string;
+            safeAddress: string;
+        };
+        evidenceTier: EnvelopeRef['evidenceTier'];
+        publishedAt: number;
+    };
+    artifacts: CorpusArtifact[];
+}
+export interface HarnessLayer {
+    readonly config: ResolvedHarnessLayerConfig;
+    corpus: {
+        /**
+         * Query the corpus and return records whose solverType / role /
+         * artifactType / ref / task cid contains `query` (case-insensitive).
+         * Empty query returns everything fetched (up to `limit`).
+         *
+         * By default the result is collapsed to lineage heads: a skill record
+         * superseded (or deprecated) by a same-operator record in the fetched page
+         * is dropped (#1462). Pass `includeSuperseded: true` to disable the
+         * collapse and see every record.
+         */
+        search(query: string, opts?: {
+            limit?: number;
+            kind?: 'skill' | 'trace';
+            includeSuperseded?: boolean;
+        }): Promise<CorpusSearchHit[]>;
+        /** Fetch a record by ref (manifest CID from a search hit), including artifact bytes. */
+        get(ref: string): Promise<CorpusRecord>;
+    };
+}
+export declare function createHarnessLayer(config?: HarnessLayerConfig): HarnessLayer;