@jinn-network/jinn-layer 0.1.0

package/dist/seed-import/state.js

@@ -0,0 +1,120 @@
+/**
+ * Seed-import idempotency state (issue #1771, folding the idempotency AC
+ * originally scoped to #1772/R2 — R4 has no dependency on R1 so it ships
+ * here; see the #1771 PR body for the rationale).
+ *
+ * Both seed lanes (skill seeds in `execute.ts`, evidence-episode seeds in
+ * `episode-execute.ts`) publish through this shared store: a small
+ * identity -> {contentHash, envelopeRef} map that each `execute*()` consults
+ * before publishing. Re-running an import over unchanged content is a no-op
+ * (a `skipped` row; no new envelope); re-running over CHANGED content
+ * republishes and points the new record's provenance at the prior
+ * `envelopeRef` via `supersedes` — skills carry it in
+ * `SkillArtifactV1.provenance.supersedes` (client/src/types/skill-artifact.ts,
+ * already schema'd for this, issue #1462); episodes carry it in the
+ * `seed.attribution` step attribute (episode-fetch.ts's step convention),
+ * since the frozen `jinn.trace-envelope.v0` has no top-level field for it.
+ *
+ * File-backed by default (`~/.jinn-client/harness-layer/seed-import-state.json`,
+ * mirroring `ledger.ts`'s convention) so real CLI runs persist across
+ * invocations; tests inject `createMemorySeedImportState()`.
+ *
+ * Deliberately NOT a corpus query: idempotency here answers "did *I* already
+ * publish this exact seed identity, unchanged?" — a question the operator's
+ * own local state answers without a network round trip. It does not detect a
+ * differently-identified duplicate already sitting in the shared corpus
+ * (two seeds, two identities, same content) — that is the consumer-side
+ * content-key dedup (rescope plan §3.3) and the testnet hygiene sweep
+ * (#1776), not a publish-time concern.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { z } from 'zod';
+import { canonicalJson } from '@jinn-network/core';
+import { sha256Hex } from '../execution-publish.js';
+export const DEFAULT_SEED_IMPORT_STATE_PATH = join(homedir(), '.jinn-client', 'harness-layer', 'seed-import-state.json');
+export const SeedPublicationRecordSchema = z.strictObject({
+    /** sha256 over the canonical JSON of the seed's meaningful content. */
+    contentHash: z.string().min(1),
+    /** The published wrapper envelope CID (the corpus ref) — the corpus's own identity for the record. */
+    envelopeRef: z.string().min(1),
+    publishedAt: z.iso.datetime(),
+});
+const SeedImportStateFileSchema = z.record(z.string(), SeedPublicationRecordSchema);
+/** In-memory store — tests, and any embedder that does not want on-disk state. */
+export function createMemorySeedImportState(initial = {}) {
+    const state = new Map(Object.entries(initial));
+    return {
+        get: (identity) => state.get(identity),
+        set: (identity, record) => {
+            state.set(identity, SeedPublicationRecordSchema.parse(record));
+        },
+    };
+}
+/**
+ * File-backed store (JSON map, `~/.jinn-client/harness-layer/seed-import-state.json`
+ * by default) — read-modify-write on every `set()`. Fine at seed-import's
+ * scale (dozens to low hundreds of curated, human-approved entries via the
+ * plan/execute gate), not a database.
+ *
+ * A corrupt/foreign state file is FAIL-CLOSED: reads and writes throw rather
+ * than treating it as empty and destroying supersedes lineage. Persistence
+ * writes a complete same-directory temp file and atomically renames it over
+ * the destination, so interruption cannot leave a partial JSON document.
+ */
+export function createFileSeedImportState(path = DEFAULT_SEED_IMPORT_STATE_PATH, opts = {}) {
+    const warn = opts.onWarning;
+    let warned = false;
+    const read = () => {
+        if (!existsSync(path))
+            return {};
+        try {
+            return SeedImportStateFileSchema.parse(JSON.parse(readFileSync(path, 'utf-8')));
+        }
+        catch (cause) {
+            const message = `[harness-layer] seed-import state at ${path} is unreadable; refusing to continue so publication lineage is preserved`;
+            if (!warned) {
+                warned = true;
+                warn?.(message);
+            }
+            throw new Error(message, { cause });
+        }
+    };
+    return {
+        get(identity) {
+            return read()[identity];
+        },
+        set(identity, record) {
+            const all = read();
+            all[identity] = SeedPublicationRecordSchema.parse(record);
+            const dir = dirname(path);
+            mkdirSync(dir, { recursive: true });
+            const tempPath = join(dir, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+            try {
+                writeFileSync(tempPath, JSON.stringify(all, null, 2) + '\n', 'utf-8');
+                renameSync(tempPath, path);
+            }
+            catch (cause) {
+                try {
+                    rmSync(tempPath, { force: true });
+                }
+                catch {
+                    // Preserve the persistence failure that triggered cleanup.
+                }
+                throw cause;
+            }
+        },
+    };
+}
+/**
+ * Deterministic content fingerprint for idempotency: sha256 over the
+ * RFC 8785 canonical JSON of the seed's meaningful fields (the caller
+ * decides which fields are "meaningful" — e.g. excludes capture-time-only
+ * fields like `capturedAt`). Two calls over the same logical content always
+ * agree, regardless of key order.
+ */
+export function hashSeedContent(value) {
+    return sha256Hex(canonicalJson(value));
+}

package/dist/signal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Distribution signal — where is real usage concentrating (plan Task 7,
+ * issue #1314; spec §7).
+ *
+ * v0 clustering is a **tag rollup**: an envelope's primary (first)
+ * distribution tag is its cluster; the cluster's `topTags` are the other
+ * tags' frequencies inside it. Deliberately crude — spec §8 says crude
+ * counts are enough for v0 — and replaceable by an upstream clustering
+ * endpoint without changing the output shape.
+ *
+ * Seeds are excluded from every number by default (`provenance:
+ * 'imported'`): seeds provide day-one usefulness but are not demand. The
+ * `includeSeeds` option exists for the demonstrate-it-live toggle in the
+ * explorer view, never as a default.
+ */
+export interface SignalInput {
+    /** distributionTags from the trace envelope (first tag = primary). */
+    tags: string[];
+    provenance: 'contributed' | 'imported' | 'derived-from-history';
+    /** Contributor identity (operator Safe address). */
+    contributor: string;
+}
+export interface SignalRow {
+    cluster: string;
+    envelopeCount: number;
+    contributorCount: number;
+    /** Co-occurring tags in the cluster, most frequent first (primary excluded). */
+    topTags: string[];
+}
+export interface SignalOptions {
+    /** Fold `provenance: 'imported'` entries back into the counts. Default false. */
+    includeSeeds?: boolean;
+    /** Cap on topTags per cluster. Default 5. */
+    topTagsLimit?: number;
+}
+export declare function computeSignal(entries: SignalInput[], opts?: SignalOptions): SignalRow[];

package/dist/signal.js

@@ -0,0 +1,48 @@
+/**
+ * Distribution signal — where is real usage concentrating (plan Task 7,
+ * issue #1314; spec §7).
+ *
+ * v0 clustering is a **tag rollup**: an envelope's primary (first)
+ * distribution tag is its cluster; the cluster's `topTags` are the other
+ * tags' frequencies inside it. Deliberately crude — spec §8 says crude
+ * counts are enough for v0 — and replaceable by an upstream clustering
+ * endpoint without changing the output shape.
+ *
+ * Seeds are excluded from every number by default (`provenance:
+ * 'imported'`): seeds provide day-one usefulness but are not demand. The
+ * `includeSeeds` option exists for the demonstrate-it-live toggle in the
+ * explorer view, never as a default.
+ */
+export function computeSignal(entries, opts = {}) {
+    const topTagsLimit = opts.topTagsLimit ?? 5;
+    const clusters = new Map();
+    for (const entry of entries) {
+        if (entry.provenance === 'imported' && !opts.includeSeeds)
+            continue;
+        const primary = entry.tags[0];
+        if (!primary)
+            continue;
+        const cluster = clusters.get(primary) ?? {
+            envelopes: 0,
+            contributors: new Set(),
+            tagCounts: new Map(),
+        };
+        cluster.envelopes += 1;
+        cluster.contributors.add(entry.contributor);
+        for (const tag of entry.tags.slice(1)) {
+            cluster.tagCounts.set(tag, (cluster.tagCounts.get(tag) ?? 0) + 1);
+        }
+        clusters.set(primary, cluster);
+    }
+    return [...clusters.entries()]
+        .map(([cluster, agg]) => ({
+        cluster,
+        envelopeCount: agg.envelopes,
+        contributorCount: agg.contributors.size,
+        topTags: [...agg.tagCounts.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .slice(0, topTagsLimit)
+            .map(([tag]) => tag),
+    }))
+        .sort((a, b) => b.envelopeCount - a.envelopeCount || a.cluster.localeCompare(b.cluster));
+}

package/dist/signing.d.ts

@@ -0,0 +1,8 @@
+export interface SignedCanonical {
+    canonicalJson: string;
+    hash: `0x${string}`;
+    sig: `0x${string}`;
+    signer: `0x${string}`;
+}
+/** Sign canonical JSON with raw secp256k1 ECDSA (no EIP-191 prefix). */
+export declare function signCanonical(value: unknown, privateKey: `0x${string}`, signerAddress: `0x${string}`): Promise<SignedCanonical>;

package/dist/signing.js

@@ -0,0 +1,21 @@
+import { hexToBytes, keccak256, toHex } from 'viem';
+import { sign } from 'viem/accounts';
+import { canonicalJson } from '@jinn-network/core';
+/** Sign canonical JSON with raw secp256k1 ECDSA (no EIP-191 prefix). */
+export async function signCanonical(value, privateKey, signerAddress) {
+    const canonical = canonicalJson(value);
+    const hash = keccak256(new TextEncoder().encode(canonical));
+    const signature = await sign({ hash, privateKey });
+    const recoveryByte = signature.yParity ?? (signature.v === 28n ? 1 : 0);
+    const sig = toHex(new Uint8Array([
+        ...hexToBytes(signature.r),
+        ...hexToBytes(signature.s),
+        recoveryByte,
+    ]));
+    return {
+        canonicalJson: canonical,
+        hash,
+        sig,
+        signer: signerAddress,
+    };
+}

package/dist/skill-package.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { SKILL_ARTIFACT_TYPE } from '@jinn-network/core';
+export { SKILL_ARTIFACT_TYPE };
+/**
+ * The distiller-side provenance meta carried on a `SkillPackage` (and embedded
+ * as `metadata.jinn` frontmatter in EXPORT renders). The canonical stored form
+ * is `SkillProvenanceSchema` in `client/src/types/skill-artifact.ts`;
+ * `publishSkill()` maps this onto it (`provenance` → `sourceEnvelopeCids`,
+ * `distilledFrom` is derived as its length there and not stored twice).
+ */
+export declare const SkillPackageMetaSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"jinn.skill.v1">;
+    distribution: z.ZodString;
+    verifiabilityTier: z.ZodString;
+    distilledFrom: z.ZodNumber;
+    provenance: z.ZodArray<z.ZodString>;
+    distillPromptSha256: z.ZodOptional<z.ZodString>;
+    distilledAt: z.ZodOptional<z.ZodString>;
+    seedSource: z.ZodOptional<z.ZodString>;
+    skillKind: z.ZodOptional<z.ZodEnum<{
+        "strategic-pattern": "strategic-pattern";
+        "failure-lesson": "failure-lesson";
+        contrastive: "contrastive";
+        "cross-instance": "cross-instance";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        experimental: "experimental";
+        stable: "stable";
+        deprecated: "deprecated";
+    }>>;
+    evidenceTier: z.ZodOptional<z.ZodEnum<{
+        contrastive: "contrastive";
+        stable: "stable";
+        deprecated: "deprecated";
+        "single-example": "single-example";
+        "recurring-pattern": "recurring-pattern";
+        "user-confirmed": "user-confirmed";
+    }>>;
+    sourceTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    targetTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    uses: z.ZodOptional<z.ZodNumber>;
+    positiveFeedback: z.ZodOptional<z.ZodNumber>;
+    negativeFeedback: z.ZodOptional<z.ZodNumber>;
+    distillModel: z.ZodOptional<z.ZodString>;
+    evidenceTokens: z.ZodOptional<z.ZodNumber>;
+    skillTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SkillPackageMeta = z.infer<typeof SkillPackageMetaSchema>;
+export interface SkillPackage {
+    name: string;
+    description: string;
+    license: string | null;
+    jinn: SkillPackageMeta;
+    body: string;
+}
+export declare function assertConformantName(name: string): void;
+/**
+ * Emit a conformant SKILL.md: YAML frontmatter then the markdown body verbatim.
+ *
+ * Default (EXPORT mode) embeds the `metadata.jinn` provenance block so a
+ * standalone SKILL.md written to disk carries its provenance. Pass
+ * `{ embedProvenance: false }` when rendering the `skill.skillMd` stored inside
+ * a `SkillArtifactV1` — there the structured provenance object is canonical and
+ * embedding a second copy would create drift.
+ */
+export declare function buildSkillMarkdown(pkg: SkillPackage, opts?: {
+    embedProvenance?: boolean;
+}): string;
+/** Inverse of buildSkillMarkdown (EXPORT mode); throws on a non-conformant package. */
+export declare function parseSkillMarkdown(md: string): SkillPackage;

package/dist/skill-package.js

@@ -0,0 +1,141 @@
+/**
+ * The layer-2 consumable package builder: renders/parses a `jinn.skill.v1`
+ * conformant Agent-Skill package (spec/2026-07-06-distillation-v1.md §5,
+ * reconciled 2026-07-07 with the shipped #1394 substrate).
+ *
+ * A skill is a `<name>/SKILL.md` package — standard skills.sh / Vercel shape —
+ * so it is drop-in installable by the wider `skills` ecosystem.
+ *
+ * Division of labour after the #1394 reconciliation:
+ *   - `client/src/types/skill-artifact.ts` (#1394, shipped) owns the CANONICAL
+ *     stored form: `SkillArtifactV1` with structured `SkillProvenanceSchema`.
+ *   - `./skill.ts` (shipped) owns consume-side recognition (`extractSkill`).
+ *   - THIS module is the distiller-side package builder/renderer: the
+ *     `SkillPackage` shape the distiller produces, and SKILL.md
+ *     rendering/parsing. `buildSkillMarkdown` embeds the `metadata.jinn`
+ *     provenance block only in EXPORT mode (default) — when a package is
+ *     written to disk as a standalone SKILL.md. The stored `skill.skillMd`
+ *     inside a `SkillArtifactV1` is rendered WITHOUT the provenance block
+ *     (`embedProvenance: false`) so provenance lives in exactly one canonical
+ *     place (the structured object) and cannot drift.
+ */
+import { parse as parseYaml, Scalar, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+import { SKILL_ARTIFACT_TYPE } from '@jinn-network/core';
+export { SKILL_ARTIFACT_TYPE };
+/** skills.sh rule: name is lowercase letters/digits/hyphens and equals the dir. */
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * The distiller-side provenance meta carried on a `SkillPackage` (and embedded
+ * as `metadata.jinn` frontmatter in EXPORT renders). The canonical stored form
+ * is `SkillProvenanceSchema` in `client/src/types/skill-artifact.ts`;
+ * `publishSkill()` maps this onto it (`provenance` → `sourceEnvelopeCids`,
+ * `distilledFrom` is derived as its length there and not stored twice).
+ */
+export const SkillPackageMetaSchema = z
+    .strictObject({
+    schema: z.literal(SKILL_ARTIFACT_TYPE),
+    distribution: z.string().min(1),
+    verifiabilityTier: z.string().min(1),
+    distilledFrom: z.number().int().nonnegative(),
+    provenance: z.array(z.string().min(1)),
+    distillPromptSha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    distilledAt: z.string().optional(),
+    seedSource: z.string().optional(),
+    skillKind: z.enum(['strategic-pattern', 'failure-lesson', 'contrastive', 'cross-instance']).optional(),
+    status: z.enum(['experimental', 'stable', 'deprecated']).optional(),
+    evidenceTier: z
+        .enum(['single-example', 'recurring-pattern', 'contrastive', 'user-confirmed', 'stable', 'deprecated'])
+        .optional(),
+    sourceTools: z.array(z.string().min(1)).optional(),
+    targetTools: z.array(z.string().min(1)).optional(),
+    uses: z.number().int().nonnegative().optional(),
+    positiveFeedback: z.number().int().nonnegative().optional(),
+    negativeFeedback: z.number().int().nonnegative().optional(),
+    // Auditability (spec §5, v0.5): the distilling model + a deterministic
+    // ceil(chars/4) token estimate of input vs body (the compression ratio).
+    distillModel: z.string().min(1).optional(),
+    evidenceTokens: z.number().int().nonnegative().optional(),
+    skillTokens: z.number().int().nonnegative().optional(),
+})
+    // Corroboration vs audit: `distilledFrom` is the DISTINCT-INSTANCE
+    // corroboration count (§6 — retries at one problem are one unit, not N),
+    // while `provenance` anchors EVERY audited source trace. Under group
+    // retention (#1478) one instance can contribute many traces, so
+    // `distilledFrom <= provenance.length` (a skill cannot corroborate across
+    // more distinct instances than it has traces), and is ≥1 whenever any trace
+    // is anchored. This keeps the ecosystem-facing "distilled from N" claim
+    // honest as a breadth signal instead of inflating with retry count.
+    .refine((m) => m.distilledFrom <= m.provenance.length && (m.provenance.length === 0 || m.distilledFrom >= 1), {
+    message: 'distilledFrom must be between 1 and provenance.length (distinct-instance corroboration ≤ audited traces)',
+});
+export function assertConformantName(name) {
+    if (!NAME_RE.test(name)) {
+        throw new Error(`skill name "${name}" is not conformant (lowercase letters/digits/hyphens only)`);
+    }
+}
+function quotedYamlString(value) {
+    const scalar = new Scalar(value);
+    scalar.type = Scalar.QUOTE_DOUBLE;
+    return scalar;
+}
+function renderableJinnMeta(jinn) {
+    return {
+        ...jinn,
+        ...(jinn.distilledAt ? { distilledAt: quotedYamlString(jinn.distilledAt) } : {}),
+    };
+}
+function normalizeParsedJinnMeta(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const record = { ...value };
+    if (record.distilledAt instanceof Date) {
+        record.distilledAt = record.distilledAt.toISOString();
+    }
+    return record;
+}
+/**
+ * Emit a conformant SKILL.md: YAML frontmatter then the markdown body verbatim.
+ *
+ * Default (EXPORT mode) embeds the `metadata.jinn` provenance block so a
+ * standalone SKILL.md written to disk carries its provenance. Pass
+ * `{ embedProvenance: false }` when rendering the `skill.skillMd` stored inside
+ * a `SkillArtifactV1` — there the structured provenance object is canonical and
+ * embedding a second copy would create drift.
+ */
+export function buildSkillMarkdown(pkg, opts = {}) {
+    assertConformantName(pkg.name);
+    const jinn = SkillPackageMetaSchema.parse(pkg.jinn);
+    const embed = opts.embedProvenance ?? true;
+    const frontmatter = stringifyYaml({
+        name: pkg.name,
+        description: pkg.description,
+        license: pkg.license,
+        ...(embed ? { metadata: { jinn: renderableJinnMeta(jinn) } } : {}),
+    });
+    return `---\n${frontmatter}---\n${pkg.body}`;
+}
+/** Inverse of buildSkillMarkdown (EXPORT mode); throws on a non-conformant package. */
+export function parseSkillMarkdown(md) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(md);
+    if (!m)
+        throw new Error('skill markdown is missing a YAML frontmatter block');
+    const doc = parseYaml(m[1]);
+    if (doc === null || typeof doc !== 'object') {
+        throw new Error('skill frontmatter did not parse to an object');
+    }
+    const name = String(doc.name ?? '');
+    assertConformantName(name);
+    if (typeof doc.description !== 'string' || doc.description.length === 0) {
+        throw new Error('skill frontmatter is missing a description');
+    }
+    const metadata = doc.metadata;
+    const jinn = SkillPackageMetaSchema.parse(normalizeParsedJinnMeta(metadata?.jinn));
+    return {
+        name,
+        description: doc.description,
+        license: doc.license == null ? null : String(doc.license),
+        jinn,
+        body: m[2] ?? '',
+    };
+}

package/dist/skill.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Skill recognition (#1394): the shared install-path helper.
+ *
+ * `extractSkill(record)` prefers a first-class `jinn.skill.v1` artifact and
+ * falls back to the seeded shape (episode/legacy trace artifact ->
+ * `seed:skill-md` step -> `skill.md` attribute + `seed.attribution`),
+ * synthesising an equivalent provenance block from the embedded fields.
+ */
+import { type SkillArtifactV1 } from '@jinn-network/core';
+import type { CorpusRecord } from './consume.js';
+export interface ExtractedSkill {
+    skill: SkillArtifactV1;
+    /** Which carrier the skill came from. */
+    shape: 'jinn.skill.v1' | 'seeded-episode' | 'seeded-trace';
+}
+/**
+ * Extract the skill carried by a corpus record, or null when the record
+ * carries none. Throws when a `jinn.skill.v1` artifact is present but
+ * malformed — a corrupt first-class skill is an error, not a fall-through.
+ */
+export declare function extractSkill(record: CorpusRecord): ExtractedSkill | null;

package/dist/skill.js

@@ -0,0 +1,77 @@
+/**
+ * Skill recognition (#1394): the shared install-path helper.
+ *
+ * `extractSkill(record)` prefers a first-class `jinn.skill.v1` artifact and
+ * falls back to the seeded shape (episode/legacy trace artifact ->
+ * `seed:skill-md` step -> `skill.md` attribute + `seed.attribution`),
+ * synthesising an equivalent provenance block from the embedded fields.
+ */
+import { z } from 'zod/v3';
+import { SKILL_ARTIFACT_TYPE, SkillArtifactV1Schema, } from '@jinn-network/core';
+import { EpisodeV1Schema } from '@jinn-network/plugin';
+import { EPISODE_ARTIFACT_TYPE, TRACE_ENVELOPE_ARTIFACT_TYPE, } from './publish.js';
+import { parseTraceEnvelopeV0 } from './envelope.js';
+import { frontmatterName, skillSlug } from './seed-import/execute.js';
+const SeedAttributionSchema = z.object({
+    skill: z.string().min(1),
+    source: z.string().min(1),
+    licence: z.string().nullable(),
+});
+function parseJson(content) {
+    return JSON.parse(content.toString('utf-8'));
+}
+/**
+ * Extract the skill carried by a corpus record, or null when the record
+ * carries none. Throws when a `jinn.skill.v1` artifact is present but
+ * malformed — a corrupt first-class skill is an error, not a fall-through.
+ */
+export function extractSkill(record) {
+    const skillArtifact = record.artifacts.find((a) => a.artifactType === SKILL_ARTIFACT_TYPE);
+    if (skillArtifact) {
+        return {
+            skill: SkillArtifactV1Schema.parse(parseJson(skillArtifact.content)),
+            shape: 'jinn.skill.v1',
+        };
+    }
+    const episodeArtifact = record.artifacts.find((a) => a.artifactType === EPISODE_ARTIFACT_TYPE);
+    const traceArtifact = episodeArtifact
+        ? undefined
+        : record.artifacts.find((a) => a.artifactType === TRACE_ENVELOPE_ARTIFACT_TYPE);
+    const carrier = episodeArtifact ?? traceArtifact;
+    if (!carrier)
+        return null;
+    let steps;
+    try {
+        steps = episodeArtifact
+            ? EpisodeV1Schema.parse(parseJson(carrier.content)).trajectory
+            : parseTraceEnvelopeV0(parseJson(carrier.content)).steps;
+    }
+    catch {
+        return null; // malformed evidence carrier — do not silently use a second shape
+    }
+    const step = steps.find((candidate) => candidate.name === 'seed:skill-md');
+    const skillMd = step?.attributes['skill.md'];
+    if (typeof skillMd !== 'string' || skillMd.length === 0)
+        return null;
+    const attribution = SeedAttributionSchema.safeParse(step.attributes['seed.attribution']);
+    const seed = attribution.success ? attribution.data : undefined;
+    return {
+        skill: {
+            schemaVersion: SKILL_ARTIFACT_TYPE,
+            skill: {
+                name: frontmatterName(skillMd) ?? (seed ? skillSlug(seed.skill) : 'skill'),
+                skillMd,
+            },
+            files: [],
+            provenance: {
+                kind: 'imported',
+                // [] for seed imports (the schema's documented convention, matching
+                // first-class seed artifacts) — callers already hold record.ref.
+                sourceEnvelopeCids: [],
+                operator: { safeAddress: record.envelope.participant.safeAddress },
+                ...(seed ? { seed } : {}),
+            },
+        },
+        shape: episodeArtifact ? 'seeded-episode' : 'seeded-trace',
+    };
+}

package/dist/snapshot-transcript.d.ts

@@ -0,0 +1,54 @@
+/**
+ * system_snapshot extraction — donation unwrap + ustar read + transcript
+ * lookup (issue #1472, spec §8).
+ *
+ * The engine tars each solve's working dir into a `system_snapshot` artifact
+ * (hand-rolled POSIX ustar + gzip, `client/src/harnesses/engine/packaging.ts`
+ * `createWorkdirTarball`) and publishes it donation-wrapped
+ * (`jinn.artifact.donation.v1`: JSON with base64 `data`). Inside is the
+ * harness's raw stdout transcript (`.claude-code/stdout.jsonl`,
+ * `.codex-code/stdout.jsonl`) — the solve's actual reasoning, which
+ * `jinn.trajectory.v1` does NOT carry (2 artifact.emit spans only; #1473
+ * tracks fixing that at solve time).
+ *
+ * `unwrapDonation` mirrors the module-private `decodeDonationArtifact`
+ * (`@jinn-network/core/corpus-read`) and additionally verifies the decoded
+ * bytes hash to the declared sha256 (tamper check). The ustar reader mirrors
+ * the writer: regular files only, names ≤100 chars, no PAX/GNU extensions —
+ * a malformed header ends iteration rather than throwing. Decompression is
+ * bomb-guarded via zlib's `maxOutputLength`.
+ */
+import { type TranscriptSpanInput } from '@jinn-network/core/trajectory';
+/** Gzip-bomb guard: snapshots observed live are ≤ ~300 KB compressed. */
+export declare const MAX_SNAPSHOT_DECOMPRESSED_BYTES: number;
+export interface TarEntry {
+    name: string;
+    bytes: Buffer;
+}
+export interface SolveTranscript {
+    harness: 'claude-code' | 'codex';
+    jsonl: string;
+}
+/**
+ * Decode a `jinn.artifact.donation.v1` wrapper to its raw bytes. Throws on a
+ * non-donation shape, a declared-sha mismatch against `expectedSha256`, or
+ * decoded bytes that do not hash to the declared sha (tamper check — parity
+ * plus-one with corpus/acquire.ts `decodeDonationArtifact`).
+ */
+export declare function unwrapDonation(raw: unknown, expectedSha256: string): Buffer;
+/**
+ * Gunzip (bomb-guarded) + read a POSIX ustar archive into entries. Regular
+ * files only; a malformed/truncated header or size field ends iteration
+ * (best-effort read of what is intact, never an infinite loop).
+ */
+export declare function untarGz(tarGz: Buffer): TarEntry[];
+/** Locate the solve transcript among snapshot entries, or null if absent. */
+export declare function findSolveTranscript(entries: TarEntry[]): SolveTranscript | null;
+/**
+ * End-to-end: donation wrapper JSON → the solve transcript, or null when the
+ * snapshot carries none (hermes, or transcript-less). Throws on unwrap /
+ * decompression failures — the caller treats any throw as "no enrichment".
+ */
+export declare function extractSnapshotTranscript(wrapper: unknown, expectedSha256: string): SolveTranscript | null;
+/** Parse snapshot stdout with the same canonical typed-span parser as the live path. */
+export declare function parseSolveTranscript(transcript: SolveTranscript): TranscriptSpanInput[];