@jinn-network/jinn-layer 0.1.0

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

@@ -0,0 +1,119 @@
+/**
+ * Evidence-episode seed source (issue #1771, rescope plan §4.2-§4.4).
+ *
+ * Stage 1's rescoped retrieval serves evidence records, not skill records
+ * (docs/superpowers/plans/2026-07-16-jinn-plugin-stage-1-rescope-plan.md
+ * §3.1). The shared testnet corpus had almost no evidence to serve — skills.sh
+ * skill seeds only. This source reads a directory of hand-authored
+ * seed-episode JSON files (each transformed offline from a REAL completed
+ * session per the runbook, docs/runbooks/stage1-evidence-seeding.md) and
+ * feeds them through the SAME `capture() -> publish()` path the skill lane
+ * uses (`episode-execute.ts`). The resulting envelope remains identifiable
+ * as a seed on the wire through `provenance: 'imported'`, the seed importer
+ * harness/session identity, the `seed-import` tag, and `seed:*` steps. The
+ * selected scrub profile is a local implementation fact proved by code and
+ * tests; `TraceEnvelopeV0` does not publish a scrub-component manifest.
+ *
+ * Step convention (so a future retrieval-side packet projector — rescope
+ * plan §3.2 `projectKnowledgePacket`, R1/#1770 — has an obvious, discoverable
+ * shape to read): every content step's `attributes` carries
+ *   'seed.step.label' — one of the §3.2 excerpt labels
+ *                        ('failure' | 'fix' | 'command' | 'diff' | 'note')
+ *   'seed.step.title' — a short human title
+ *   'seed.step.text'  — the excerpt content itself
+ * and a final step carries the episode-level metadata:
+ *   'seed.synthesis'   — the authored how-it-was-solved text (§3.2 `synthesis`)
+ *   'seed.attribution' — { repo, baseCommit?, origin, sourceUrl?, supersedes? }
+ * No bespoke fixture format: this is exactly the frozen jinn.trace-envelope.v0
+ * step shape (spec §3.1), the same free-form-attribute convention the
+ * existing `seed:skill-md` skill-seed step already uses.
+ */
+import { z } from 'zod';
+/** Rescope plan §3.2 excerpt labels — the knowledge-packet projection's vocabulary. */
+export declare const SEED_EPISODE_EXCERPT_LABELS: readonly ["failure", "fix", "command", "diff", "note"];
+export declare const SeedEpisodeExcerptLabelSchema: z.ZodEnum<{
+    command: "command";
+    failure: "failure";
+    fix: "fix";
+    diff: "diff";
+    note: "note";
+}>;
+export type SeedEpisodeExcerptLabel = z.infer<typeof SeedEpisodeExcerptLabelSchema>;
+export declare const SeedEpisodeStepSchema: z.ZodObject<{
+    label: z.ZodEnum<{
+        command: "command";
+        failure: "failure";
+        fix: "fix";
+        diff: "diff";
+        note: "note";
+    }>;
+    title: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type SeedEpisodeStep = z.infer<typeof SeedEpisodeStepSchema>;
+/**
+ * A seed-episode file — the canonical captured-evidence contract (issue
+ * #1771): task summary, ordered steps with real commands/outputs (a source
+ * episode carries at least one `failure` and its `fix`; distractors are
+ * freeform), outcome + verifiability tier, tags, attribution, and an
+ * authored synthesis. Strict: an unknown field is a malformed fixture, not
+ * silently tolerated.
+ */
+export declare const SeedEpisodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    repo: z.ZodString;
+    baseCommit: z.ZodOptional<z.ZodString>;
+    taskSummary: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        label: z.ZodEnum<{
+            command: "command";
+            failure: "failure";
+            fix: "fix";
+            diff: "diff";
+            note: "note";
+        }>;
+        title: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    outcome: z.ZodObject<{
+        status: z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            abandoned: "abandoned";
+        }>;
+        verifiabilityTier: z.ZodEnum<{
+            "user-accepted": "user-accepted";
+            "tests-passed": "tests-passed";
+            "evaluator-verified": "evaluator-verified";
+        }>;
+    }, z.core.$strict>;
+    synthesis: z.ZodString;
+    attribution: z.ZodObject<{
+        origin: z.ZodString;
+        sourceUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SeedEpisode = z.infer<typeof SeedEpisodeSchema>;
+/** Canonical identity and content approved by an episode report row. */
+export declare function episodeContentDigest(episode: SeedEpisode): string;
+/** Parse an untrusted value (a seed-episode JSON file) as a SeedEpisode; throws ZodError. */
+export declare function parseSeedEpisode(input: unknown): SeedEpisode;
+export interface EpisodeSource {
+    name: string;
+    list(): Promise<SeedEpisode[]>;
+}
+export interface LocalEpisodeSeedSourceOptions {
+    maxFiles?: number;
+    maxFileBytes?: number;
+    rejectSymlinks?: boolean;
+}
+/**
+ * Local directory seed source: every `*.episode.json` file in `dir`,
+ * validated against `SeedEpisodeSchema`. Sorted by filename for
+ * deterministic plan/execute ordering (reproducible report files; the
+ * fixture-lint test pins this too). Files not matching the `.episode.json`
+ * suffix (e.g. the skill-shaped distractor fixtures) are ignored by
+ * construction — episodes and skills are separate lanes.
+ */
+export declare function createLocalEpisodeSeedSource(dir: string, options?: LocalEpisodeSeedSourceOptions): EpisodeSource;

package/dist/seed-import/episode-fetch.js

@@ -0,0 +1,137 @@
+/**
+ * Evidence-episode seed source (issue #1771, rescope plan §4.2-§4.4).
+ *
+ * Stage 1's rescoped retrieval serves evidence records, not skill records
+ * (docs/superpowers/plans/2026-07-16-jinn-plugin-stage-1-rescope-plan.md
+ * §3.1). The shared testnet corpus had almost no evidence to serve — skills.sh
+ * skill seeds only. This source reads a directory of hand-authored
+ * seed-episode JSON files (each transformed offline from a REAL completed
+ * session per the runbook, docs/runbooks/stage1-evidence-seeding.md) and
+ * feeds them through the SAME `capture() -> publish()` path the skill lane
+ * uses (`episode-execute.ts`). The resulting envelope remains identifiable
+ * as a seed on the wire through `provenance: 'imported'`, the seed importer
+ * harness/session identity, the `seed-import` tag, and `seed:*` steps. The
+ * selected scrub profile is a local implementation fact proved by code and
+ * tests; `TraceEnvelopeV0` does not publish a scrub-component manifest.
+ *
+ * Step convention (so a future retrieval-side packet projector — rescope
+ * plan §3.2 `projectKnowledgePacket`, R1/#1770 — has an obvious, discoverable
+ * shape to read): every content step's `attributes` carries
+ *   'seed.step.label' — one of the §3.2 excerpt labels
+ *                        ('failure' | 'fix' | 'command' | 'diff' | 'note')
+ *   'seed.step.title' — a short human title
+ *   'seed.step.text'  — the excerpt content itself
+ * and a final step carries the episode-level metadata:
+ *   'seed.synthesis'   — the authored how-it-was-solved text (§3.2 `synthesis`)
+ *   'seed.attribution' — { repo, baseCommit?, origin, sourceUrl?, supersedes? }
+ * No bespoke fixture format: this is exactly the frozen jinn.trace-envelope.v0
+ * step shape (spec §3.1), the same free-form-attribute convention the
+ * existing `seed:skill-md` skill-seed step already uses.
+ */
+import { lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { OutcomeStatusSchema, VerifiabilityTierSchema } from '../envelope.js';
+import { hashSeedContent } from './state.js';
+/** Rescope plan §3.2 excerpt labels — the knowledge-packet projection's vocabulary. */
+export const SEED_EPISODE_EXCERPT_LABELS = ['failure', 'fix', 'command', 'diff', 'note'];
+export const SeedEpisodeExcerptLabelSchema = z.enum(SEED_EPISODE_EXCERPT_LABELS);
+export const SeedEpisodeStepSchema = z.strictObject({
+    label: SeedEpisodeExcerptLabelSchema,
+    title: z.string().min(1),
+    text: z.string().min(1),
+});
+/**
+ * A seed-episode file — the canonical captured-evidence contract (issue
+ * #1771): task summary, ordered steps with real commands/outputs (a source
+ * episode carries at least one `failure` and its `fix`; distractors are
+ * freeform), outcome + verifiability tier, tags, attribution, and an
+ * authored synthesis. Strict: an unknown field is a malformed fixture, not
+ * silently tolerated.
+ */
+export const SeedEpisodeSchema = z.strictObject({
+    /** Stable seed identity — the idempotency key (state.ts) and filename stem. */
+    id: z.string().min(1),
+    /** `owner/repo` the episode re-performs work in/against. */
+    repo: z.string().min(1),
+    /** Full 40-char commit sha the episode was re-performed AT (pre-fix state), when applicable. */
+    baseCommit: z.string().regex(/^[0-9a-f]{40}$/, 'full 40-char commit sha').optional(),
+    taskSummary: z.string().min(1).max(500),
+    tags: z.array(z.string().min(1)).min(1),
+    steps: z.array(SeedEpisodeStepSchema).min(1),
+    outcome: z.strictObject({
+        status: OutcomeStatusSchema,
+        verifiabilityTier: VerifiabilityTierSchema,
+    }),
+    /** 3-6 sentence how-it-was-solved text (rescope plan §3.2 `synthesis`). */
+    synthesis: z.string().min(1),
+    attribution: z.strictObject({
+        /**
+         * How this episode entered the corpus — stated honestly. Vocabulary in
+         * use (freeform by schema; document new values in
+         * docs/runbooks/stage1-evidence-seeding.md):
+         * - 'operator-recorded-session' — transformed from a real recorded
+         *   session; pair with `sourceUrl` when it re-performs a merged fix.
+         * - 'synthetic-selection-distractor' — hand-authored negative/contrast
+         *   material, explicitly synthetic and paired with the unverified
+         *   `user-accepted` tier (PR #1779 review).
+         */
+        origin: z.string().min(1),
+        /** Link to the real merged fix, when the episode re-performs one. */
+        sourceUrl: z.string().min(1).optional(),
+    }),
+});
+/** Canonical identity and content approved by an episode report row. */
+export function episodeContentDigest(episode) {
+    return hashSeedContent({
+        id: episode.id,
+        repo: episode.repo,
+        baseCommit: episode.baseCommit ?? null,
+        taskSummary: episode.taskSummary,
+        tags: episode.tags,
+        steps: episode.steps,
+        outcome: episode.outcome,
+        synthesis: episode.synthesis,
+        attribution: episode.attribution,
+    });
+}
+/** Parse an untrusted value (a seed-episode JSON file) as a SeedEpisode; throws ZodError. */
+export function parseSeedEpisode(input) {
+    return SeedEpisodeSchema.parse(input);
+}
+/**
+ * Local directory seed source: every `*.episode.json` file in `dir`,
+ * validated against `SeedEpisodeSchema`. Sorted by filename for
+ * deterministic plan/execute ordering (reproducible report files; the
+ * fixture-lint test pins this too). Files not matching the `.episode.json`
+ * suffix (e.g. the skill-shaped distractor fixtures) are ignored by
+ * construction — episodes and skills are separate lanes.
+ */
+export function createLocalEpisodeSeedSource(dir, options = {}) {
+    return {
+        name: `local-episodes:${dir}`,
+        async list() {
+            const files = readdirSync(dir)
+                .filter((file) => file.endsWith('.episode.json'))
+                .sort();
+            if (options.maxFiles !== undefined && files.length > options.maxFiles) {
+                throw new Error(`episode directory contains ${files.length} candidate files; maximum is ${options.maxFiles}`);
+            }
+            return files.map((file) => {
+                const path = join(dir, file);
+                const stats = lstatSync(path);
+                if (options.rejectSymlinks && stats.isSymbolicLink()) {
+                    throw new Error(`episode candidate must not be a symbolic link: ${file}`);
+                }
+                if (options.rejectSymlinks && !stats.isFile()) {
+                    throw new Error(`episode candidate must be a regular file: ${file}`);
+                }
+                if (options.maxFileBytes !== undefined &&
+                    stats.size > options.maxFileBytes) {
+                    throw new Error(`episode candidate ${file} exceeds ${options.maxFileBytes} byte limit`);
+                }
+                return parseSeedEpisode(JSON.parse(readFileSync(path, 'utf-8')));
+            });
+        },
+    };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * `planEpisodes()` — list + structural validation, ZERO writes (mirrors
+ * `plan.ts` for the evidence-episode source, issue #1771). Episodes are
+ * first-party content (no licence gate); the only structural failure this
+ * catches is a duplicate `id` within one batch — a same-identity collision
+ * would otherwise make idempotency (state.ts) apply to whichever file lists
+ * second, silently dropping the first from the report.
+ */
+import { type EpisodeSource } from './episode-fetch.js';
+import type { EpisodeImportReport } from './episode-report.js';
+export declare function planEpisodes(source: EpisodeSource): Promise<EpisodeImportReport>;

package/dist/seed-import/episode-plan.js

@@ -0,0 +1,27 @@
+/**
+ * `planEpisodes()` — list + structural validation, ZERO writes (mirrors
+ * `plan.ts` for the evidence-episode source, issue #1771). Episodes are
+ * first-party content (no licence gate); the only structural failure this
+ * catches is a duplicate `id` within one batch — a same-identity collision
+ * would otherwise make idempotency (state.ts) apply to whichever file lists
+ * second, silently dropping the first from the report.
+ */
+import { episodeContentDigest } from './episode-fetch.js';
+export async function planEpisodes(source) {
+    const episodes = await source.list();
+    const seen = new Set();
+    return episodes.map((episode) => {
+        const duplicate = seen.has(episode.id);
+        seen.add(episode.id);
+        return {
+            id: episode.id,
+            taskSummary: episode.taskSummary,
+            tags: episode.tags,
+            contentDigest: episodeContentDigest(episode),
+            verdict: duplicate ? 'skip' : 'import',
+            reason: duplicate
+                ? `duplicate id "${episode.id}" in source — first occurrence wins`
+                : 'first-party recorded episode',
+        };
+    });
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The EpisodeImportReport — the evidence-episode analogue of `report.ts`'s
+ * ImportReport (issue #1771). Episodes are first-party authored content (no
+ * upstream licence to gate on, unlike the skills.sh skill lane) so `verdict`
+ * here is structural, not licence-based: 'skip' only for a duplicate `id`
+ * within the same batch (see `episode-plan.ts`). `seed execute --episodes-dir`
+ * still reads this report as the approval-gate artifact — nothing publishes
+ * that was not on the list a human reviewed, and `contentDigest` binds each
+ * row to the exact canonical episode content present at planning time.
+ */
+import { z } from 'zod';
+export declare const EpisodeImportReportRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    taskSummary: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    contentDigest: z.ZodString;
+    verdict: z.ZodEnum<{
+        import: "import";
+        skip: "skip";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type EpisodeImportReportRow = z.infer<typeof EpisodeImportReportRowSchema>;
+export declare const EpisodeImportReportSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    taskSummary: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    contentDigest: z.ZodString;
+    verdict: z.ZodEnum<{
+        import: "import";
+        skip: "skip";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strict>>;
+export type EpisodeImportReport = z.infer<typeof EpisodeImportReportSchema>;
+/** Parse an untrusted value (e.g. an edited report file); throws ZodError. */
+export declare function parseEpisodeImportReport(input: unknown): EpisodeImportReport;
+/** Human-readable report table for the terminal. */
+export declare function renderEpisodeImportReport(report: EpisodeImportReport): string;

package/dist/seed-import/episode-report.js

@@ -0,0 +1,36 @@
+/**
+ * The EpisodeImportReport — the evidence-episode analogue of `report.ts`'s
+ * ImportReport (issue #1771). Episodes are first-party authored content (no
+ * upstream licence to gate on, unlike the skills.sh skill lane) so `verdict`
+ * here is structural, not licence-based: 'skip' only for a duplicate `id`
+ * within the same batch (see `episode-plan.ts`). `seed execute --episodes-dir`
+ * still reads this report as the approval-gate artifact — nothing publishes
+ * that was not on the list a human reviewed, and `contentDigest` binds each
+ * row to the exact canonical episode content present at planning time.
+ */
+import { z } from 'zod';
+export const EpisodeImportReportRowSchema = z.strictObject({
+    id: z.string().min(1),
+    taskSummary: z.string().min(1),
+    tags: z.array(z.string().min(1)),
+    /** SHA-256 over the canonical episode content the operator approved. */
+    contentDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    verdict: z.enum(['import', 'skip']),
+    reason: z.string().min(1),
+});
+export const EpisodeImportReportSchema = z.array(EpisodeImportReportRowSchema);
+/** Parse an untrusted value (e.g. an edited report file); throws ZodError. */
+export function parseEpisodeImportReport(input) {
+    return EpisodeImportReportSchema.parse(input);
+}
+/** Human-readable report table for the terminal. */
+export function renderEpisodeImportReport(report) {
+    if (report.length === 0)
+        return 'Empty report — no episodes listed.';
+    const lines = [`${report.length} episode(s)`, ''];
+    for (const row of report) {
+        lines.push(`${row.verdict === 'import' ? 'IMPORT' : 'skip  '}  ${row.id}`, `        summary  ${row.taskSummary}`, `        tags     ${row.tags.join(', ')}`, `        digest   ${row.contentDigest}`, `        reason   ${row.reason}`, '');
+    }
+    lines.pop();
+    return lines.join('\n');
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `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 { type HarnessPublishDeps } from '../publish.js';
+import type { SeedSource } from './fetch.js';
+import type { ImportReport } from './report.js';
+import { type SeedImportStateStore } from './state.js';
+export interface ImportResult {
+    imported: Array<{
+        skill: string;
+        envelopeRef: string;
+        anchorTx: string | null;
+        /** Publication succeeded, but local lineage state needs operator recovery. */
+        stateWarning?: string;
+        /** Anchor succeeded, but the local publication ledger needs recovery. */
+        ledgerWarning?: string;
+    }>;
+    skipped: Array<{
+        skill: string;
+        reason: string;
+    }>;
+    errors: Array<{
+        skill: string;
+        error: string;
+    }>;
+}
+/**
+ * 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 declare function frontmatterName(skillMd: string): string | null;
+/** Last path segment of a registry-style skill id (`owner/repo/slug`). */
+export declare function skillSlug(skillId: string): string;
+export declare function execute(report: ImportReport, source: SeedSource, deps: HarnessPublishDeps, opts?: {
+    state?: SeedImportStateStore;
+}): Promise<ImportResult>;