@jinn-network/jinn-layer 0.1.0

package/dist/seed-import/execute.js

@@ -0,0 +1,245 @@
+/**
+ * `execute()` — publish the approved import rows through the Task-4 path
+ * (plan Task 6, spec §7).
+ *
+ * Each imported skill becomes a synthetic captured task carrying the
+ * SKILL.md as its single step, runs through the SAME mandatory scrub
+ * (`capture()`) and the SAME publish/anchor path (`publish()`) as a real
+ * contribution — one publish path, per the 2026-07-02 schema review — with
+ * `provenance: 'imported'` and attribution metadata in the step attributes.
+ * Seeds are thereby excluded from the demand signal and from emissions
+ * eligibility by every provenance-aware reader.
+ *
+ * The licence gate is structural, not advisory: execute() re-checks each
+ * row's licence from the freshly-fetched source. A verdict hand-edited to
+ * `import` over a non-allowlisted licence is refused — widening the gate is
+ * a code change to the disclosed allowlist, reviewable in a PR, not a
+ * report-file edit.
+ *
+ * Idempotent by seed identity (issue #1771, `state.ts`): re-running execute
+ * over an unchanged skill publishes nothing new (a `skipped` row instead);
+ * re-running over a CHANGED skill (different skillMd/description/licence/
+ * source) republishes and sets the new record's
+ * `provenance.supersedes` to the prior envelopeRef. `opts.state` defaults to
+ * a fresh in-memory store per call, so existing callers that never pass one
+ * see unchanged behaviour (every row always publishes) — the CLI wires a
+ * file-backed store for real runs (cli.ts, `seed execute`).
+ */
+import { capture } from '../capture.js';
+import { buildSeedScrubPipeline } from '@jinn-network/core/scrub';
+import { publish, PublishLedgerError, } from '../publish.js';
+import { checkLicence } from './licence.js';
+import { createMemorySeedImportState, hashSeedContent, } from './state.js';
+/** Caps from the frozen envelope schema (envelope-v0.md size limits). */
+const MAX_TAG_CHARS = 64;
+const MAX_TAGS = 16;
+/**
+ * Extract `name:` from a SKILL.md YAML frontmatter block, if present.
+ * Deliberately a line-parser, not a YAML dependency — skill frontmatter
+ * names are plain scalars; anything more exotic simply yields no tag.
+ */
+export function frontmatterName(skillMd) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
+    if (!match)
+        return null;
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = /^name:\s*(.+)$/.exec(line.trim());
+        if (kv) {
+            const value = kv[1].trim().replace(/^["']|["']$/g, '').trim();
+            return value || null;
+        }
+    }
+    return null;
+}
+/** Last path segment of a registry-style skill id (`owner/repo/slug`). */
+export function skillSlug(skillId) {
+    const segments = skillId.split('/').filter((s) => s.length > 0);
+    return segments[segments.length - 1] ?? skillId;
+}
+/**
+ * Seed tags (#1343): the seed marker, the repo, the skill slug (last path
+ * segment), and the SKILL.md frontmatter name when it declares one. Tags are
+ * freeform under the frozen schema (envelope-v0.md: no fixed taxonomy) but
+ * the size caps are structural — dedupe, clamp to 64 chars, cap at 16.
+ * The signal's authoritative seed marker stays `provenance: 'imported'`;
+ * `seed-import` is honest labelling on top.
+ */
+function seedTags(skill) {
+    const segments = skill.skill.split('/').filter((s) => s.length > 0);
+    const repoName = segments[1] ?? skill.skill;
+    const slug = skillSlug(skill.skill);
+    const name = frontmatterName(skill.skillMd);
+    const tags = [];
+    for (const candidate of ['seed-import', repoName, slug, ...(name ? [name] : [])]) {
+        const tag = candidate.trim().slice(0, MAX_TAG_CHARS);
+        if (tag && !tags.includes(tag))
+            tags.push(tag);
+    }
+    return tags.slice(0, MAX_TAGS);
+}
+function toCapturedTask(skill, now) {
+    const nano = `${now.getTime()}000000`;
+    return {
+        session: {
+            sessionId: `seed:${skill.skill}`,
+            capturedAt: now.toISOString(),
+        },
+        task: {
+            summary: `Seed import: ${skill.skill}${skill.description ? ` — ${skill.description}` : ''}`,
+            distributionTags: seedTags(skill),
+        },
+        environment: {
+            harness: { name: 'jinn-layer-seed-import', version: '0.1.0' },
+            model: 'none',
+            tools: [],
+        },
+        steps: [
+            {
+                spanId: 'seed-1',
+                parentSpanId: null,
+                name: 'seed:skill-md',
+                startTimeUnixNano: nano,
+                endTimeUnixNano: nano,
+                attributes: {
+                    'skill.md': skill.skillMd,
+                    'seed.attribution': {
+                        skill: skill.skill,
+                        source: skill.source,
+                        licence: skill.licence,
+                    },
+                },
+                redactedKeys: [],
+            },
+        ],
+        outcome: {
+            // user-accepted is literal here: the human approved this exact list.
+            status: 'completed',
+            verifiabilityTier: 'user-accepted',
+        },
+        cost: { durationMs: 0 },
+        provenance: 'imported',
+    };
+}
+/** First-class skill artifact for a seed (#1394). Companion-file fetch is #1381. */
+function toSkillArtifact(skill, safeAddress, supersedes) {
+    return {
+        schemaVersion: 'jinn.skill.v1',
+        skill: {
+            name: frontmatterName(skill.skillMd) ?? skillSlug(skill.skill),
+            ...(skill.description !== undefined ? { description: skill.description } : {}),
+            skillMd: skill.skillMd,
+        },
+        files: [],
+        provenance: {
+            kind: 'imported',
+            sourceEnvelopeCids: [],
+            operator: { safeAddress },
+            seed: { skill: skill.skill, source: skill.source, licence: skill.licence },
+            ...(supersedes ? { supersedes } : {}),
+        },
+    };
+}
+/** The content fields that define "did this seed change" for idempotency (state.ts). */
+function skillContentFingerprint(skill) {
+    return {
+        skillMd: skill.skillMd,
+        description: skill.description ?? null,
+        licence: skill.licence,
+        source: skill.source,
+    };
+}
+export async function execute(report, source, deps, opts = {}) {
+    const skills = new Map((await source.list()).map((s) => [s.skill, s]));
+    const result = { imported: [], skipped: [], errors: [] };
+    const now = deps.now?.() ?? new Date();
+    // Seed profile (#1409): deterministic secret detectors only. Skill seeds in
+    // this lane are public, licence-checked prose, not operator trace data — the
+    // probabilistic stages false-positive on SKILL.md content and defaced
+    // the anchored corpus. Capture stays mandatory and fail-closed.
+    const seedScrubPipeline = buildSeedScrubPipeline();
+    const state = opts.state ?? createMemorySeedImportState();
+    for (const row of report) {
+        if (row.verdict === 'skip') {
+            result.skipped.push({ skill: row.skill, reason: row.reason });
+            continue;
+        }
+        try {
+            const skill = skills.get(row.skill);
+            if (!skill)
+                throw new Error(`skill ${row.skill} not found in source ${source.name}`);
+            const licence = checkLicence(skill.licence);
+            if (licence.verdict !== 'import') {
+                throw new Error(`licence gate refused ${row.skill}: ${licence.reason}`);
+            }
+            const identity = `skill:${skill.skill}`;
+            const contentHash = hashSeedContent(skillContentFingerprint(skill));
+            let prior;
+            try {
+                prior = state.get(identity);
+            }
+            catch (err) {
+                result.errors.push({
+                    skill: row.skill,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                break;
+            }
+            if (prior && prior.contentHash === contentHash) {
+                result.skipped.push({ skill: row.skill, reason: `unchanged since ${prior.envelopeRef}` });
+                continue;
+            }
+            const pending = await capture(toCapturedTask(skill, now), {
+                pipeline: seedScrubPipeline,
+            });
+            let published;
+            let ledgerWarning;
+            try {
+                published = await publish(pending, deps, {
+                    skill: toSkillArtifact(skill, deps.participant.safeAddress, prior?.envelopeRef),
+                });
+            }
+            catch (err) {
+                if (err instanceof PublishLedgerError) {
+                    published = err.result;
+                    ledgerWarning = err.message;
+                }
+                else {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    result.errors.push({
+                        skill: row.skill,
+                        error: `publication outcome unknown; do not auto-retry: ${detail}`,
+                    });
+                    break;
+                }
+            }
+            if (published.vetoed)
+                throw new Error('unexpected veto on seed publish');
+            let stateWarning;
+            try {
+                state.set(identity, { contentHash, envelopeRef: published.envelopeRef, publishedAt: now.toISOString() });
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                stateWarning =
+                    `published ${published.envelopeRef}, but seed-import state persistence failed: ${detail}; ` +
+                        'recovery required before retrying this seed';
+            }
+            result.imported.push({
+                skill: row.skill,
+                envelopeRef: published.envelopeRef,
+                anchorTx: published.anchorTx,
+                ...(ledgerWarning ? { ledgerWarning } : {}),
+                ...(stateWarning ? { stateWarning } : {}),
+            });
+            if (ledgerWarning || stateWarning)
+                break;
+        }
+        catch (err) {
+            result.errors.push({
+                skill: row.skill,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return result;
+}

package/dist/seed-import/fetch.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Seed sources (plan Task 6, spec §7).
+ *
+ * skills.sh (the first registry, per spec D8) exposes no stable public
+ * listing API — its entries are GitHub repos. The durable listing surface is
+ * therefore a **disclosed input list** of `owner/repo[#path]` entries (which
+ * also matches D9's bounded-allowlist posture: nothing imports that was not
+ * on a list a human read), resolved against the GitHub API for the licence
+ * (`GET /repos/{owner}/{repo}` → `license.spdx_id`) and the SKILL.md
+ * content.
+ */
+import { z } from 'zod';
+export interface SeedSkill {
+    /** Registry-style id, e.g. `vercel-labs/skills/find-skills`. */
+    skill: string;
+    /** Canonical source URL (the attribution target). */
+    source: string;
+    /** SPDX id, or null when the repo declares none. */
+    licence: string | null;
+    description?: string;
+    /** The SKILL.md content (the layer-2 consumable, spec §5). */
+    skillMd: string;
+}
+/**
+ * Zod mirror of `SeedSkill` (issue #1771): the wire shape of a skill-shaped
+ * seed fixture on disk (e.g. `fixtures/stage1-seeds/distractor-skill-*.json`),
+ * used by the fixture-lint test to validate skill-shaped fixtures without a
+ * live GitHub source. Not consumed by `createGithubSeedSource` — that source
+ * still speaks `SeedSkill` directly.
+ */
+export declare const SeedSkillSchema: z.ZodObject<{
+    skill: z.ZodString;
+    source: z.ZodString;
+    licence: z.ZodNullable<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    skillMd: z.ZodString;
+}, z.core.$strict>;
+export interface SeedSource {
+    name: string;
+    list(): Promise<SeedSkill[]>;
+}
+/** One line of the disclosed input list: `owner/repo` or `owner/repo#sub/path`. */
+export interface SeedListEntry {
+    owner: string;
+    repo: string;
+    /** Path to the skill directory inside the repo (contains SKILL.md). */
+    path?: string;
+}
+export declare function parseSeedListEntry(line: string): SeedListEntry;
+export interface GithubSeedSourceOptions {
+    /** The disclosed input list. */
+    entries: SeedListEntry[];
+    /** GitHub token (raises rate limits; optional for small lists). */
+    token?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * GitHub-backed seed source over a disclosed entry list. Licence comes from
+ * the repo's declared licence; SKILL.md from `{path}/SKILL.md` (repo root
+ * when no path is given).
+ */
+export declare function createGithubSeedSource(options: GithubSeedSourceOptions): SeedSource;

package/dist/seed-import/fetch.js

@@ -0,0 +1,82 @@
+/**
+ * Seed sources (plan Task 6, spec §7).
+ *
+ * skills.sh (the first registry, per spec D8) exposes no stable public
+ * listing API — its entries are GitHub repos. The durable listing surface is
+ * therefore a **disclosed input list** of `owner/repo[#path]` entries (which
+ * also matches D9's bounded-allowlist posture: nothing imports that was not
+ * on a list a human read), resolved against the GitHub API for the licence
+ * (`GET /repos/{owner}/{repo}` → `license.spdx_id`) and the SKILL.md
+ * content.
+ */
+import { z } from 'zod';
+/**
+ * Zod mirror of `SeedSkill` (issue #1771): the wire shape of a skill-shaped
+ * seed fixture on disk (e.g. `fixtures/stage1-seeds/distractor-skill-*.json`),
+ * used by the fixture-lint test to validate skill-shaped fixtures without a
+ * live GitHub source. Not consumed by `createGithubSeedSource` — that source
+ * still speaks `SeedSkill` directly.
+ */
+export const SeedSkillSchema = z.strictObject({
+    skill: z.string().min(1),
+    source: z.string().min(1),
+    licence: z.string().min(1).nullable(),
+    description: z.string().min(1).optional(),
+    skillMd: z.string().min(1),
+});
+export function parseSeedListEntry(line) {
+    const [repoPart, path] = line.trim().split('#', 2);
+    const segments = (repoPart ?? '').split('/').filter((s) => s.length > 0);
+    if (segments.length !== 2) {
+        throw new Error(`invalid seed list entry "${line}" — expected owner/repo or owner/repo#path`);
+    }
+    return {
+        owner: segments[0],
+        repo: segments[1],
+        ...(path ? { path } : {}),
+    };
+}
+const GITHUB_API = 'https://api.github.com';
+async function githubJson(url, token, fetchImpl) {
+    const res = await fetchImpl(url, {
+        headers: {
+            accept: 'application/vnd.github+json',
+            'user-agent': 'jinn-harness-layer-seed-import',
+            ...(token ? { authorization: `Bearer ${token}` } : {}),
+        },
+    });
+    if (!res.ok)
+        throw new Error(`GitHub ${res.status} for ${url}`);
+    return res.json();
+}
+/**
+ * GitHub-backed seed source over a disclosed entry list. Licence comes from
+ * the repo's declared licence; SKILL.md from `{path}/SKILL.md` (repo root
+ * when no path is given).
+ */
+export function createGithubSeedSource(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return {
+        name: 'github-seed-list',
+        async list() {
+            const skills = [];
+            for (const entry of options.entries) {
+                const repoUrl = `${GITHUB_API}/repos/${entry.owner}/${entry.repo}`;
+                const repo = (await githubJson(repoUrl, options.token, fetchImpl));
+                const skillMdPath = entry.path ? `${entry.path}/SKILL.md` : 'SKILL.md';
+                const content = (await githubJson(`${repoUrl}/contents/${skillMdPath}`, options.token, fetchImpl));
+                if (!content.content || content.encoding !== 'base64') {
+                    throw new Error(`no SKILL.md at ${entry.owner}/${entry.repo}/${skillMdPath}`);
+                }
+                skills.push({
+                    skill: [entry.owner, entry.repo, ...(entry.path ? [entry.path] : [])].join('/'),
+                    source: repo.html_url ?? `https://github.com/${entry.owner}/${entry.repo}`,
+                    licence: repo.license?.spdx_id ?? null,
+                    ...(repo.description ? { description: repo.description } : {}),
+                    skillMd: Buffer.from(content.content, 'base64').toString('utf-8'),
+                });
+            }
+            return skills;
+        },
+    };
+}

package/dist/seed-import/licence.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-skill licence gate (plan Task 6, spec §7 / D8).
+ *
+ * The allowlist is bounded and disclosed: permissive licences import (with
+ * attribution carried in the published envelope); anything else — including
+ * a missing licence — skips with a stated reason. Copyleft is excluded not
+ * as a legal judgement but as a posture: the corpus republishes content, and
+ * share-alike terms make that a per-licence analysis we have not done.
+ */
+/** SPDX ids that import (with attribution). Bounded, disclosed. */
+export declare const IMPORT_LICENCE_ALLOWLIST: readonly string[];
+export interface LicenceVerdict {
+    verdict: 'import' | 'skip';
+    reason: string;
+}
+/** Map an SPDX id (or null = no licence found) to an import verdict. */
+export declare function checkLicence(spdx: string | null | undefined): LicenceVerdict;

package/dist/seed-import/licence.js

@@ -0,0 +1,36 @@
+/**
+ * Per-skill licence gate (plan Task 6, spec §7 / D8).
+ *
+ * The allowlist is bounded and disclosed: permissive licences import (with
+ * attribution carried in the published envelope); anything else — including
+ * a missing licence — skips with a stated reason. Copyleft is excluded not
+ * as a legal judgement but as a posture: the corpus republishes content, and
+ * share-alike terms make that a per-licence analysis we have not done.
+ */
+/** SPDX ids that import (with attribution). Bounded, disclosed. */
+export const IMPORT_LICENCE_ALLOWLIST = [
+    'MIT',
+    'Apache-2.0',
+    'BSD-2-Clause',
+    'BSD-3-Clause',
+    'ISC',
+    'CC0-1.0',
+    'Unlicense',
+    'MIT-0',
+];
+/** Map an SPDX id (or null = no licence found) to an import verdict. */
+export function checkLicence(spdx) {
+    if (!spdx || spdx === 'NOASSERTION') {
+        return {
+            verdict: 'skip',
+            reason: 'no licence found — cannot republish without one',
+        };
+    }
+    if (IMPORT_LICENCE_ALLOWLIST.includes(spdx)) {
+        return { verdict: 'import', reason: `${spdx} — permissive, import with attribution` };
+    }
+    return {
+        verdict: 'skip',
+        reason: `${spdx} is not on the import allowlist (permissive licences only)`,
+    };
+}

package/dist/seed-import/plan.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `plan()` — fetch + licence-check, ZERO writes (plan Task 6).
+ *
+ * Takes only a SeedSource; it cannot publish, anchor or touch the ledger by
+ * construction (no publish deps in the signature). Its output is the
+ * ImportReport the human approves before `execute()` may run.
+ */
+import type { SeedSource } from './fetch.js';
+import type { ImportReport } from './report.js';
+export declare function plan(source: SeedSource): Promise<ImportReport>;

package/dist/seed-import/plan.js

@@ -0,0 +1,21 @@
+/**
+ * `plan()` — fetch + licence-check, ZERO writes (plan Task 6).
+ *
+ * Takes only a SeedSource; it cannot publish, anchor or touch the ledger by
+ * construction (no publish deps in the signature). Its output is the
+ * ImportReport the human approves before `execute()` may run.
+ */
+import { checkLicence } from './licence.js';
+export async function plan(source) {
+    const skills = await source.list();
+    return skills.map((skill) => {
+        const { verdict, reason } = checkLicence(skill.licence);
+        return {
+            skill: skill.skill,
+            source: skill.source,
+            licence: skill.licence,
+            verdict,
+            reason,
+        };
+    });
+}

package/dist/seed-import/report.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The ImportReport — the approval-gate artifact (plan Task 6).
+ *
+ * `seed plan` renders and writes this; Oak reads and approves (editing
+ * verdicts if needed) BEFORE `seed execute` runs. Nothing lands on chain
+ * that was not on this list.
+ */
+import { z } from 'zod';
+export declare const ImportReportRowSchema: z.ZodObject<{
+    skill: z.ZodString;
+    source: z.ZodString;
+    licence: z.ZodNullable<z.ZodString>;
+    verdict: z.ZodEnum<{
+        import: "import";
+        skip: "skip";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type ImportReportRow = z.infer<typeof ImportReportRowSchema>;
+export declare const ImportReportSchema: z.ZodArray<z.ZodObject<{
+    skill: z.ZodString;
+    source: z.ZodString;
+    licence: z.ZodNullable<z.ZodString>;
+    verdict: z.ZodEnum<{
+        import: "import";
+        skip: "skip";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strict>>;
+export type ImportReport = z.infer<typeof ImportReportSchema>;
+/** Parse an untrusted value (e.g. an edited report file); throws ZodError. */
+export declare function parseImportReport(input: unknown): ImportReport;
+/** Human-readable report table for the terminal. */
+export declare function renderImportReport(report: ImportReport): string;

package/dist/seed-import/report.js

@@ -0,0 +1,31 @@
+/**
+ * The ImportReport — the approval-gate artifact (plan Task 6).
+ *
+ * `seed plan` renders and writes this; Oak reads and approves (editing
+ * verdicts if needed) BEFORE `seed execute` runs. Nothing lands on chain
+ * that was not on this list.
+ */
+import { z } from 'zod';
+export const ImportReportRowSchema = z.strictObject({
+    skill: z.string().min(1),
+    source: z.string().min(1),
+    licence: z.string().min(1).nullable(),
+    verdict: z.enum(['import', 'skip']),
+    reason: z.string().min(1),
+});
+export const ImportReportSchema = z.array(ImportReportRowSchema);
+/** Parse an untrusted value (e.g. an edited report file); throws ZodError. */
+export function parseImportReport(input) {
+    return ImportReportSchema.parse(input);
+}
+/** Human-readable report table for the terminal. */
+export function renderImportReport(report) {
+    if (report.length === 0)
+        return 'Empty report — no skills listed.';
+    const lines = [`${report.length} skill(s)`, ''];
+    for (const row of report) {
+        lines.push(`${row.verdict === 'import' ? 'IMPORT' : 'skip  '}  ${row.skill}`, `        licence  ${row.licence ?? '- (none found)'}`, `        source   ${row.source}`, `        reason   ${row.reason}`, '');
+    }
+    lines.pop();
+    return lines.join('\n');
+}

package/dist/seed-import/state.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 { z } from 'zod';
+export declare const DEFAULT_SEED_IMPORT_STATE_PATH: string;
+export declare const SeedPublicationRecordSchema: z.ZodObject<{
+    contentHash: z.ZodString;
+    envelopeRef: z.ZodString;
+    publishedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type SeedPublicationRecord = z.infer<typeof SeedPublicationRecordSchema>;
+export interface SeedImportStateStore {
+    /** The prior publication of this identity, or undefined if never published. */
+    get(identity: string): SeedPublicationRecord | undefined;
+    /** Record identity's latest publication (overwrites any prior entry). */
+    set(identity: string, record: SeedPublicationRecord): void;
+}
+/** In-memory store — tests, and any embedder that does not want on-disk state. */
+export declare function createMemorySeedImportState(initial?: Record<string, SeedPublicationRecord>): SeedImportStateStore;
+export interface FileSeedImportStateOptions {
+    /**
+     * Optional sink for the fail-closed corrupt-state warning. The read still
+     * throws; this hook only lets a CLI surface the same diagnostic separately.
+     */
+    onWarning?: (message: string) => void;
+}
+/**
+ * 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 declare function createFileSeedImportState(path?: string, opts?: FileSeedImportStateOptions): SeedImportStateStore;
+/**
+ * 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 declare function hashSeedContent(value: unknown): string;