@jinn-network/jinn-layer 0.1.0

package/dist/consume.js

@@ -0,0 +1,280 @@
+/**
+ * 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 { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createCorpus, createHttpCorpusDiscovery, queryCaptureMeta as queryCaptureMetaCore, } from '@jinn-network/core/corpus-read';
+import { SignedEnvelopeSchema, SKILL_ARTIFACT_TYPE, } from '@jinn-network/core';
+import { SqliteCorpusStore } from './corpus-store.js';
+import { extractSkill } from './skill.js';
+export 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 const DEFAULT_IPFS_GATEWAY_URL = 'https://gateway.autonolas.tech';
+const DEFAULT_SEARCH_LIMIT = 50;
+function matchesQuery(hit, needle) {
+    if (needle === '')
+        return true;
+    const haystack = [
+        hit.solverType,
+        hit.role,
+        hit.ref,
+        hit.task?.cid ?? '',
+        hit.operator.safeAddress,
+        ...hit.artifactTypes,
+    ].join('\n').toLowerCase();
+    return haystack.includes(needle.toLowerCase());
+}
+function toSearchHit(ref, envelope) {
+    return {
+        title: `${envelope.solverType} / ${envelope.role}`,
+        ref: ref.manifestCid,
+        solverType: envelope.solverType,
+        role: envelope.role,
+        artifactTypes: envelope.artifacts.map((a) => a.artifactType),
+        kind: envelope.artifacts.some((a) => a.artifactType === SKILL_ARTIFACT_TYPE) ? 'skill' : 'trace',
+        evidenceTier: ref.evidenceTier,
+        generatedAt: envelope.generatedAt,
+        publishedAt: ref.publishedAt,
+        operator: {
+            agentId: ref.operator.agentId,
+            // The indexer does not store safeAddress; enrich from the manifest.
+            safeAddress: ref.operator.safeAddress || envelope.participant.safeAddress,
+        },
+        task: envelope.task
+            ? { cid: envelope.task.cid, requestId: envelope.task.requestId }
+            : null,
+    };
+}
+/** Synthesize an EnvelopeRef for a bare manifest CID (get-by-ref path). */
+function refForCid(manifestCid) {
+    return {
+        manifestCid,
+        manifestHash: '',
+        operator: { agentId: '', safeAddress: '' },
+        evidenceTier: 'unknown',
+        publishedAt: 0,
+    };
+}
+export function createHarnessLayer(config = {}) {
+    const discoveryUrl = config.discoveryUrl ?? DEFAULT_TESTNET_DISCOVERY_URL;
+    const resolved = {
+        discoveryUrl,
+        ipfsGatewayUrl: config.ipfsGatewayUrl ?? DEFAULT_IPFS_GATEWAY_URL,
+        dbPath: config.store?.path
+            ?? config.dbPath
+            ?? join(homedir(), '.jinn-client', 'harness-layer', 'corpus-cache.db'),
+        captureMetaUrl: config.captureMetaUrl
+            ?? `${discoveryUrl.replace(/\/graphql\/?$/, '').replace(/\/$/, '')}/capture-meta`,
+    };
+    const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    const store = config.store ?? new SqliteCorpusStore(resolved.dbPath);
+    const discovery = config.discovery ?? createHttpCorpusDiscovery({
+        url: resolved.discoveryUrl,
+        fetchImpl: globalThis.fetch,
+    });
+    // `signer.privateKey` and `selfSafeAddress` are required by CorpusOptions
+    // but unused by the read paths this layer exposes (query / fetchManifest /
+    // ipfs-and-origin acquire). Placeholders, same as the read-only corpus in
+    // client/src/mcp/server.ts.
+    const corpus = createCorpus({
+        discovery,
+        ipfsGatewayUrl: resolved.ipfsGatewayUrl,
+        store,
+        signer: { privateKey: '0x0' },
+        selfSafeAddress: '0x0000000000000000000000000000000000000000',
+        parseEnvelope(input) {
+            return SignedEnvelopeSchema.parse(input);
+        },
+    }, {
+        ...(config.fetchFromIpfs ? { fetchFromIpfs: config.fetchFromIpfs } : {}),
+        ...(config.acquireFn ? { acquireFn: config.acquireFn } : {}),
+    });
+    /**
+     * Content-aware fast path (#1344): substring search over the indexer's
+     * enriched capture metadata (tags + task summary) — finds by content
+     * without any artifact fetch. Degrades to [] on any failure (older
+     * indexer, onchain mode, network error) so the manifest scan below is
+     * always the floor.
+     */
+    async function queryCaptureMeta(query, limit) {
+        return queryCaptureMetaCore({
+            url: resolved.captureMetaUrl,
+            query,
+            limit,
+            fetchImpl,
+        });
+    }
+    /**
+     * Collapse a page of hits to lineage heads (#1462). For every `kind:'skill'`
+     * hit, fetch its body and read `provenance.supersedes` / `provenance.deprecates`:
+     *   - a `deprecates: true` record hides itself, and
+     *   - a `supersedes` pointer hides its target when — and only when — the
+     *     target's operator matches this record's operator.
+     *
+     * Operator identity is the on-chain-derived `operator.agentId` the DiscoveryAPI
+     * supplies on each hit (IdentityRegistry event → indexer `row.agentId`), NOT the
+     * envelope `participant.safeAddress`. participant.safeAddress is free-form IPFS
+     * manifest content the publisher writes at will; keying the same-operator check
+     * off it would let a forged address grief default discovery. agentId is not
+     * forgeable in this way — a record is only indexed under its publisher's real
+     * agentId — so a supersede fires only against the same on-chain operator. The
+     * match is fail-safe: an absent agentId never matches, so an unattributed record
+     * collapses nothing. Residual (narrower): the supersede intent itself is not yet
+     * signature-verified end-to-end; tracked in spec/2026-07-06-distillation-v1.md §16.
+     *
+     * O(page) window (DECISION #3, no indexer change): a supersede is honored
+     * only when BOTH successor and target land in the same fetched page (spec
+     * §5/§16). Head-resolution is fail-safe: an unfetchable body hides nothing
+     * (mirrors the warn+continue on the manifest-scan path above).
+     */
+    async function resolveHeads(hits) {
+        const lineage = new Map();
+        for (const h of hits) {
+            if (h.kind !== 'skill')
+                continue;
+            try {
+                const record = await get(h.ref);
+                const prov = extractSkill(record)?.skill.provenance;
+                lineage.set(h.ref, {
+                    // Operator identity from the on-chain-derived `operator.agentId` the
+                    // DiscoveryAPI supplies on the hit (IdentityRegistry event → indexer
+                    // `row.agentId`, carried through `corpus.fetchManifest` untouched) —
+                    // NOT the envelope `participant.safeAddress`, which is free-form IPFS
+                    // manifest content the publisher writes at will (a forged value there
+                    // could grief default discovery). A record can only be indexed under
+                    // its publisher's real `agentId`, so a supersede pointer only fires
+                    // against the SAME on-chain operator.
+                    op: h.operator.agentId,
+                    supersedes: prov?.supersedes,
+                    deprecates: prov?.deprecates,
+                });
+            }
+            catch (err) {
+                console.warn(`[harness-layer] head-resolution skipping ${h.ref}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const excluded = new Set();
+        for (const [selfRef, info] of lineage) {
+            if (info.deprecates === true)
+                excluded.add(selfRef);
+            if (info.supersedes) {
+                const target = lineage.get(info.supersedes);
+                // Same-operator only, fail-safe when identity is unknown: require both
+                // agentIds non-empty and equal. An empty agentId (a backend that does
+                // not attribute the hit) never matches, so an unattributable record
+                // hides nothing rather than griefing.
+                if (target && info.op && target.op && target.op === info.op) {
+                    excluded.add(info.supersedes);
+                }
+            }
+        }
+        return hits.filter((h) => !(h.kind === 'skill' && excluded.has(h.ref)));
+    }
+    async function search(query, opts = {}) {
+        const limit = opts.limit ?? DEFAULT_SEARCH_LIMIT;
+        const hits = [];
+        const seen = new Set();
+        // Fast path: content matches from indexed capture meta. Manifest fetch
+        // per hit only (never artifact bodies).
+        for (const metaHit of await queryCaptureMeta(query, limit)) {
+            if (hits.length >= limit)
+                break;
+            try {
+                const preview = await corpus.fetchManifest(refForCid(metaHit.manifestCid));
+                const hit = toSearchHit(preview.ref, preview.envelope);
+                hits.push({
+                    ...hit,
+                    tags: Array.isArray(metaHit.tags) ? metaHit.tags : [],
+                    summary: metaHit.taskSummary,
+                    ...(typeof metaHit.repositorySlug === 'string'
+                        ? { repositorySlug: metaHit.repositorySlug }
+                        : {}),
+                    ...(typeof metaHit.synthesis === 'string'
+                        ? { synthesis: metaHit.synthesis }
+                        : {}),
+                    ...(typeof metaHit.retrievalVisible === 'boolean'
+                        ? { retrievalVisible: metaHit.retrievalVisible }
+                        : {}),
+                });
+                seen.add(metaHit.manifestCid);
+            }
+            catch (err) {
+                console.warn(`[harness-layer] skipping capture-meta hit ${metaHit.manifestCid}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const refs = await corpus.query({ limit });
+        for (const ref of refs) {
+            if (seen.has(ref.manifestCid))
+                continue;
+            let preview;
+            try {
+                preview = await corpus.fetchManifest(ref);
+            }
+            catch (err) {
+                // A single unfetchable manifest must not sink the whole search.
+                console.warn(`[harness-layer] skipping manifest ${ref.manifestCid}: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            const hit = toSearchHit(preview.ref, preview.envelope);
+            if (matchesQuery(hit, query))
+                hits.push(hit);
+            if (hits.length >= limit)
+                break;
+        }
+        // Collapse to lineage heads (#1462) unless the caller opts out. Runs before
+        // the kind filter so a superseded skill is dropped regardless of the filter.
+        const heads = opts.includeSuperseded ? hits : await resolveHeads(hits);
+        // Client-side kind filter (spec §5: the indexer has no artifactType column,
+        // so this is a best-effort filter over the fetched page — a kind-filtered
+        // search may return fewer than `limit` if other kinds consumed the budget).
+        return opts.kind ? heads.filter((h) => h.kind === opts.kind) : heads;
+    }
+    async function get(ref) {
+        const preview = await corpus.fetchManifest(refForCid(ref));
+        const envelope = await corpus.acquire(preview);
+        const artifacts = envelope.envelope.artifacts.map((a) => {
+            const content = envelope.artifactContents.get(a.sha256);
+            if (!content)
+                throw new Error(`artifact ${a.sha256} missing from acquire result`);
+            return {
+                sha256: a.sha256,
+                artifactType: a.artifactType,
+                content: content.bytes,
+                source: content.source,
+                sizeBytes: content.bytes.length,
+            };
+        });
+        return {
+            ref: envelope.ref.manifestCid,
+            envelope: envelope.envelope,
+            provenance: {
+                operator: {
+                    agentId: envelope.ref.operator.agentId,
+                    safeAddress: envelope.ref.operator.safeAddress || envelope.envelope.participant.safeAddress,
+                },
+                evidenceTier: envelope.ref.evidenceTier,
+                publishedAt: envelope.ref.publishedAt,
+            },
+            artifacts,
+        };
+    }
+    return {
+        config: resolved,
+        corpus: { search, get },
+    };
+}

package/dist/corpus-probes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Layer-side corpus doctor probes — the single shared implementation of the
+ * two "does the operator have corpus" checks the doctor renders.
+ *
+ * Two checks come out of one search against the corpus consume path:
+ *   - `corpus-reachable` — is the corpus read path answering at all?
+ *   - `corpus-content`   — did the repo-slug query find enough evidence that
+ *                         interactive pickup can actually serve?
+ *
+ * Both are shared so the Python doctor (apps/jinn-agent/plugins/jinn/doctor.py)
+ * and the layer CLI (`jinn-layer corpus probe`) render identical semantics.
+ *
+ * The content check deliberately mirrors pickup's two-layer, fail-closed
+ * retrieval allowlist (#1824): the search hit must carry the canonical mark,
+ * then the fetched trace content must carry it too. Unmarked substrate and
+ * skills never satisfy onboarding, even though they remain valid corpus data.
+ */
+import type { HarnessLayer, CorpusSearchHit } from './consume.js';
+/**
+ * How many matching corpus records a repo needs before Jinn considers itself
+ * "onboarded" for that repo. B's "enough corpus" guarantee — the sole source of
+ * truth for the K threshold, consumed by both `enoughCorpusForRepo` and the
+ * `corpus-content.ok` field below.
+ */
+export declare const CORPUS_ONBOARDING_K = 3;
+/**
+ * One doctor check result. Mirrors the Python doctor contract in
+ * apps/jinn-agent/plugins/jinn/doctor.py: a plain `{name, ok, detail}` dict with
+ * `remedy` present exactly when `ok` is false — EXCEPT informational checks,
+ * which never carry a remedy even when `ok` is false (there is nothing for the
+ * operator to fix, so there is no copy-paste command to offer). `corpus-content`
+ * is such an informational check.
+ */
+export type DoctorCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+    remedy?: string;
+};
+/**
+ * B's "enough corpus" guarantee: a repo has enough corpus when at least `k`
+ * retrieval-visible matching records survived both of pickup's visibility
+ * guards. The single source of truth for the K threshold —
+ * `corpusProbes`' `corpus-content.ok` MUST call this over the same admitted hits
+ * so the threshold cannot drift between the two.
+ */
+export declare function enoughCorpusForRepo(hits: CorpusSearchHit[], k?: number): boolean;
+/**
+ * Run the two corpus doctor probes off one corpus search plus bounded fetches
+ * for search-marked candidates.
+ *
+ * Search failures are never re-thrown: they are reported as a
+ * failing `corpus-reachable` check plus an informational (remedy-free)
+ * `corpus-content` that says it was not checked. Individual candidate fetch or
+ * decode failures simply fail closed for content counting.
+ */
+export declare function corpusProbes({ layer, repoSlug, k, }: {
+    layer: HarnessLayer;
+    repoSlug: string;
+    k?: number;
+}): Promise<DoctorCheck[]>;

package/dist/corpus-probes.js

@@ -0,0 +1,120 @@
+/**
+ * Layer-side corpus doctor probes — the single shared implementation of the
+ * two "does the operator have corpus" checks the doctor renders.
+ *
+ * Two checks come out of one search against the corpus consume path:
+ *   - `corpus-reachable` — is the corpus read path answering at all?
+ *   - `corpus-content`   — did the repo-slug query find enough evidence that
+ *                         interactive pickup can actually serve?
+ *
+ * Both are shared so the Python doctor (apps/jinn-agent/plugins/jinn/doctor.py)
+ * and the layer CLI (`jinn-layer corpus probe`) render identical semantics.
+ *
+ * The content check deliberately mirrors pickup's two-layer, fail-closed
+ * retrieval allowlist (#1824): the search hit must carry the canonical mark,
+ * then the fetched trace content must carry it too. Unmarked substrate and
+ * skills never satisfy onboarding, even though they remain valid corpus data.
+ */
+import { deriveRepositorySearchTerms, hasRetrievalMark } from '@jinn-network/plugin';
+import { createCorpusAdapter } from './adapters/corpus-adapter.js';
+/**
+ * How many matching corpus records a repo needs before Jinn considers itself
+ * "onboarded" for that repo. B's "enough corpus" guarantee — the sole source of
+ * truth for the K threshold, consumed by both `enoughCorpusForRepo` and the
+ * `corpus-content.ok` field below.
+ */
+export const CORPUS_ONBOARDING_K = 3;
+/**
+ * The consume path has no pagination cursor. Ask for a page comfortably wider
+ * than K so unmarked substrate at the front cannot hide the curated records
+ * behind it. The doctor is a full/manual check, not a session-start hot path.
+ */
+const CORPUS_PROBE_CANDIDATE_LIMIT = 50;
+/**
+ * B's "enough corpus" guarantee: a repo has enough corpus when at least `k`
+ * retrieval-visible matching records survived both of pickup's visibility
+ * guards. The single source of truth for the K threshold —
+ * `corpusProbes`' `corpus-content.ok` MUST call this over the same admitted hits
+ * so the threshold cannot drift between the two.
+ */
+export function enoughCorpusForRepo(hits, k = CORPUS_ONBOARDING_K) {
+    return hits.length >= k;
+}
+/**
+ * Run the two corpus doctor probes off one corpus search plus bounded fetches
+ * for search-marked candidates.
+ *
+ * Search failures are never re-thrown: they are reported as a
+ * failing `corpus-reachable` check plus an informational (remedy-free)
+ * `corpus-content` that says it was not checked. Individual candidate fetch or
+ * decode failures simply fail closed for content counting.
+ */
+export async function corpusProbes({ layer, repoSlug, k = CORPUS_ONBOARDING_K, }) {
+    const repoTerms = deriveRepositorySearchTerms(repoSlug);
+    // An empty term set means pickup has no repository vocabulary (for example,
+    // a two-character repo name). Probe the empty query only for reachability;
+    // it must not make arbitrary corpus records count as repo content.
+    const searchTerms = repoTerms.length > 0 ? repoTerms : [''];
+    let hits;
+    try {
+        const pages = await Promise.all(searchTerms.map((term) => layer.corpus.search(term, {
+            limit: Math.max(CORPUS_PROBE_CANDIDATE_LIMIT, k),
+        })));
+        const seen = new Set();
+        hits = pages.flat().filter((hit) => {
+            if (seen.has(hit.ref))
+                return false;
+            seen.add(hit.ref);
+            return true;
+        });
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        return [
+            {
+                name: 'corpus-reachable',
+                ok: false,
+                detail: `unreachable — ${reason}`,
+                remedy: 'check network / discovery config (JINN_DISCOVERY_URL) and re-run',
+            },
+            // Informational: never carries a remedy — there is nothing to fix here, the
+            // reachability failure above owns the remedy.
+            { name: 'corpus-content', ok: false, detail: 'not checked — corpus unreachable' },
+        ];
+    }
+    // Ranking-side visibility gate: this is the same canonical mark helper the
+    // corpus adapter uses to set KnowledgeHit.retrievalVisible. Skills are not
+    // retrieval evidence, even if a malformed producer tagged one.
+    const markedCandidates = (repoTerms.length > 0 ? hits : []).filter((hit) => hit.kind !== 'skill' && hasRetrievalMark(hit.tags ?? []));
+    // Content-side visibility gate: createCorpusAdapter is the exact decoder the
+    // plugin pickup wiring uses. It verifies the trace artifact and computes
+    // retrievalVisible from the canonical envelope distributionTags, so the
+    // doctor cannot drift into a parallel admission policy.
+    const corpus = createCorpusAdapter({ layer });
+    const admittedHits = [];
+    for (const hit of markedCandidates) {
+        if (admittedHits.length >= k)
+            break;
+        const result = await corpus.get(hit.ref);
+        if (result.status !== 'ok' || result.value === null)
+            continue;
+        if (result.value.isSkillPayload === true || result.value.retrievalVisible !== true)
+            continue;
+        admittedHits.push(hit);
+    }
+    const contentOk = enoughCorpusForRepo(admittedHits, k);
+    return [
+        // Reachable is about the read path answering; 0 records is still reachable
+        // (empty is non-blocking nothing-found, not an error).
+        { name: 'corpus-reachable', ok: true, detail: `reachable — ${hits.length} record(s)` },
+        // Informational: no remedy field EVER — a bare corpus is expected while the
+        // repo has no records yet; Jinn stays quiet until content exists.
+        {
+            name: 'corpus-content',
+            ok: contentOk,
+            detail: contentOk
+                ? `${admittedHits.length} retrieval-visible matching record(s)`
+                : 'no matching content yet; Jinn stays quiet until it exists',
+        },
+    ];
+}

package/dist/corpus-store.d.ts

@@ -0,0 +1,16 @@
+import type { CorpusStorePort, NetworkArtifactRow, SaveNetworkArtifactInput, ServedArtifactRow } from '@jinn-network/core/corpus-read';
+/**
+ * Standalone corpus cache implementing core's read-side store port. The table
+ * names and columns intentionally match the client database so an existing
+ * `JINN_LAYER_DB_PATH` remains readable after extraction.
+ */
+export declare class SqliteCorpusStore implements CorpusStorePort {
+    #private;
+    readonly path: string;
+    constructor(path: string);
+    close(): void;
+    getNetworkArtifact(sha256: string): NetworkArtifactRow | null;
+    touchNetworkArtifactUsage(sha256: string, usedAt: string): void;
+    saveNetworkArtifact(input: SaveNetworkArtifactInput): void;
+    getServedArtifact(sha256: string): ServedArtifactRow | null;
+}

package/dist/corpus-store.js

@@ -0,0 +1,101 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Standalone corpus cache implementing core's read-side store port. The table
+ * names and columns intentionally match the client database so an existing
+ * `JINN_LAYER_DB_PATH` remains readable after extraction.
+ */
+export class SqliteCorpusStore {
+    path;
+    #db;
+    constructor(path) {
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+        this.#db = new Database(path);
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS served_artifacts (
+        sha256 TEXT PRIMARY KEY,
+        artifact_type TEXT NOT NULL,
+        request_id TEXT,
+        envelope_cid TEXT,
+        content BLOB NOT NULL,
+        content_size INTEGER NOT NULL,
+        price_usdc TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS network_artifacts (
+        sha256 TEXT PRIMARY KEY,
+        artifact_type TEXT NOT NULL,
+        envelope_cid TEXT,
+        content BLOB NOT NULL,
+        content_size INTEGER NOT NULL,
+        source TEXT NOT NULL CHECK (
+          source IN ('origin', 'route-resolver', 'self-store-mirror')
+        ),
+        source_operator TEXT,
+        source_endpoint TEXT,
+        paid_amount_usdc TEXT NOT NULL,
+        fetched_at TEXT NOT NULL,
+        last_used_at TEXT NOT NULL
+      );
+    `);
+    }
+    close() {
+        this.#db.close();
+    }
+    getNetworkArtifact(sha256) {
+        const row = this.#db
+            .prepare(`SELECT sha256, artifact_type, envelope_cid, content, source,
+                source_operator, source_endpoint, paid_amount_usdc, fetched_at
+           FROM network_artifacts
+          WHERE sha256 = ?`)
+            .get(sha256);
+        return row
+            ? {
+                sha256: row.sha256,
+                artifactType: row.artifact_type,
+                content: row.content,
+                sourceOperator: row.source_operator,
+                fetchedAt: row.fetched_at,
+            }
+            : null;
+    }
+    touchNetworkArtifactUsage(sha256, usedAt) {
+        this.#db
+            .prepare('UPDATE network_artifacts SET last_used_at = ? WHERE sha256 = ?')
+            .run(usedAt, sha256);
+    }
+    saveNetworkArtifact(input) {
+        this.#db
+            .prepare(`INSERT OR REPLACE INTO network_artifacts
+           (sha256, artifact_type, envelope_cid, content, content_size, source,
+            source_operator, source_endpoint, paid_amount_usdc, fetched_at,
+            last_used_at)
+         VALUES
+           (@sha256, @artifactType, @envelopeCid, @content, @contentSize,
+            @source, @sourceOperator, @sourceEndpoint, @paidAmountUsdc,
+            @fetchedAt, @fetchedAt)`)
+            .run({
+            ...input,
+            envelopeCid: input.envelopeCid ?? null,
+            contentSize: input.content.length,
+            sourceOperator: input.sourceOperator ?? null,
+            sourceEndpoint: input.sourceEndpoint ?? null,
+        });
+    }
+    getServedArtifact(sha256) {
+        const row = this.#db
+            .prepare(`SELECT artifact_type, envelope_cid, content
+           FROM served_artifacts
+          WHERE sha256 = ?`)
+            .get(sha256);
+        return row
+            ? {
+                artifactType: row.artifact_type,
+                envelopeCid: row.envelope_cid,
+                content: row.content,
+            }
+            : null;
+    }
+}

package/dist/distill-captures.d.ts

@@ -0,0 +1,56 @@
+import type { EpisodeV1, LocalLearningSkill } from '@jinn-network/plugin';
+import { type CapturedTask } from './capture.js';
+/** Deprecated CapturedTask directory retained as a read-only fallback. */
+export declare const DEFAULT_CAPTURES_DIR: string;
+/** Canonical complete EpisodeV1 records, distinct from legacy distill captures. */
+export declare const DEFAULT_EPISODES_DIR: string;
+/** Local skills library `distill` installs into by default. */
+export declare const DEFAULT_SKILLS_INSTALL_DIR: string;
+/** How many recent own captures `distill` considers when --limit is unset. */
+export declare const DEFAULT_DISTILL_CAPTURE_LIMIT = 50;
+/**
+ * Load the operator's most recent own captures from `dir`. Every `*.json` file
+ * must be a `CapturedTask`; malformed files are skipped with a stderr warning
+ * so machine-readable stdout stays parseable.
+ */
+export declare function loadRecentCaptures(dir: string, limit: number): CapturedTask[];
+/**
+ * Project the canonical local evidence record into the input shape consumed by
+ * the existing rung-1 distillation engine. The projection is intentionally
+ * lossless for trace facts the distiller understands; episode-only state stays
+ * in the canonical record and is never copied to another store.
+ */
+export declare function episodeToCapturedTask(episode: EpisodeV1): CapturedTask;
+export interface DistillSourceOptions {
+    /** Canonical EpisodeV1 store. */
+    episodesDir: string;
+    /** Deprecated CapturedTask store, retained for read compatibility only. */
+    legacyCapturesDir?: string;
+    limit: number;
+}
+/**
+ * Load recent local-learning inputs from the canonical episode store, then
+ * merge historical CapturedTask files during the deprecation window. A
+ * canonical episode always wins for a duplicate session id, even when the old
+ * file has a later timestamp, and the limit is applied only after global sort.
+ */
+export declare function loadRecentDistillSources(options: DistillSourceOptions): Promise<CapturedTask[]>;
+/** Staging directory beside the active generated-skill directory. */
+export declare function stagingDirFor(activeDir: string): string;
+/** Derive local skill history from the canonical active/staged SKILL.md files. */
+export declare function localSkillProvenance(activeDir: string, stagedDir?: string): LocalLearningSkill[];
+/**
+ * The session ids already covered by a generated skill under any of `dirs`.
+ * Both active and staged skill dirs count so `--resume` never re-spends a
+ * capture that already produced a skill.
+ */
+export declare function coveredSessionIds(dirs: string[]): Set<string>;
+/**
+ * Map local provenance refs to human labels for run panels. Unknown refs remain
+ * unchanged so non-local provenance stays auditable.
+ */
+export declare function provenanceLabels(pkg: {
+    jinn: {
+        provenance: string[];
+    };
+}, summaryBySession: Map<string, string>): string[];