@jinn-network/plugin 0.1.0

package/dist/ports/corpus-port.d.ts

@@ -0,0 +1,63 @@
+import type { PortResult } from '../outcome.js';
+import type { KnowledgeHit } from '../schemas/knowledge-hit.js';
+/**
+ * One decoded trace step — a light structural echo of the frozen
+ * `jinn.trace-envelope.v0` step shape (`spanId`/timing/redaction bookkeeping
+ * dropped; array order is the step order). `attributes` follows the existing
+ * capture convention (`tool.args`/`tool.result`/`tool.exitCode`; see
+ * `projectKnowledgePacket`'s excerpt selection in `schemas/knowledge-packet.ts`).
+ */
+export interface CorpusRecordStep {
+    name: string;
+    attributes: Record<string, unknown>;
+}
+/**
+ * A content-bearing corpus record — the `KnowledgeHit` metadata plus decoded
+ * evidence content (rescope design §3.1/§3.2): everything
+ * `projectKnowledgePacket` needs to build a `KnowledgePacket` without any
+ * further I/O. Replaces the pre-rescope metadata-only `get()` return.
+ */
+export interface CorpusRecord {
+    ref: string;
+    task: {
+        summary: string;
+        repositorySlug?: string;
+    };
+    outcome: {
+        status: 'completed' | 'failed' | 'abandoned';
+        verifiabilityTier: 'user-accepted' | 'tests-passed' | 'evaluator-verified';
+    };
+    /** The record's own concise how-it-was-solved text, authored at capture/seed
+     *  time — never generated at retrieval time. */
+    synthesis?: string;
+    steps: CorpusRecordStep[];
+    tags: string[];
+    provenance: 'imported' | 'contributed' | 'derived-from-history';
+    /** Display attribution for the rendered packet. The adapter may fall back
+     *  to safeAddress here because cross-record dedup already happened on the
+     *  search hit's trustworthy `origin`. */
+    origin: string;
+    capturedAt: string;
+    /**
+     * True when the adapter's decode determined the record's payload is a
+     * skill package — a step carrying a string `skill.md` attribute (legacy
+     * pre-#1394 seed shape) or the record backed by a `jinn.skill.v1` artifact
+     * (first-class shape) — regardless of the search hit's wire `kind`/
+     * `payloadKind` (mono #1782: a legacy skill-shaped record classifies as
+     * `kind: 'trace'` on the wire and slips the selection-time filter).
+     * Adapter-computed fact; the core (`plugin.ts` `firstTurnPickup`) enforces
+     * exclusion — keeps the core the policy owner, the adapter the fact
+     * provider. Undefined when undetermined, including when the adapter's own
+     * detection errors — the guard fails open, exactly like an ordinary trace
+     * record.
+     */
+    isSkillPayload?: boolean;
+    /** Computed in decodeRecord from the envelope's own distributionTags (issue
+     *  #1824) — content is the truth, hit metadata is only a hint. Post-fetch
+     *  guard in firstTurnPickup drops a record whose content lacks the mark. */
+    retrievalVisible?: boolean;
+}
+export interface CorpusPort {
+    search(query: string): Promise<PortResult<KnowledgeHit[]>>;
+    get(ref: string): Promise<PortResult<CorpusRecord | null>>;
+}

package/dist/ports/corpus-port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/evidence-port.d.ts

@@ -0,0 +1,17 @@
+import type { PortResult } from '../outcome.js';
+import type { EpisodeV1 } from '../schemas/episode.js';
+export interface EvidenceListQuery {
+    limit?: number;
+}
+export interface EvidenceRetentionPolicy {
+    policy: 'local-private' | 'contribution-eligible';
+    maxEpisodes: number;
+}
+export interface EvidencePort {
+    put(episode: EpisodeV1): Promise<PortResult<{
+        episodeId: string;
+    }>>;
+    get(episodeId: string): Promise<PortResult<EpisodeV1 | null>>;
+    list(query?: EvidenceListQuery): Promise<PortResult<EpisodeV1[]>>;
+    retention(): Promise<PortResult<EvidenceRetentionPolicy>>;
+}

package/dist/ports/evidence-port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/local-learning-port.d.ts

@@ -0,0 +1,22 @@
+import type { PortResult } from '../outcome.js';
+export interface LocalLearningRun {
+    runId: string;
+    state: 'pending' | 'running' | 'done' | 'failed';
+}
+/** One locally distilled skill plus the sessions recorded in its provenance. */
+export interface LocalLearningSkill {
+    ref: string;
+    sourceSessionIds: string[];
+    state: 'staged' | 'installed';
+}
+export interface LocalLearningPort {
+    run(input: {
+        episodeIds: string[];
+    }): Promise<PortResult<{
+        runId: string;
+    }>>;
+    status(runId: string): Promise<PortResult<LocalLearningRun>>;
+    list(): Promise<PortResult<LocalLearningRun[]>>;
+    /** Optional for older adapters; history reports unavailable when absent. */
+    skills?(): Promise<PortResult<LocalLearningSkill[]>>;
+}

package/dist/ports/local-learning-port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/skills-port.d.ts

@@ -0,0 +1,12 @@
+import type { PortResult } from '../outcome.js';
+export interface SkillRecord {
+    ref: string;
+    installedAt: string;
+}
+export interface SkillsPort {
+    install(ref: string): Promise<PortResult<SkillRecord>>;
+    list(): Promise<PortResult<SkillRecord[]>>;
+    uninstall(ref: string): Promise<PortResult<{
+        ref: string;
+    }>>;
+}

package/dist/ports/skills-port.js

@@ -0,0 +1 @@
+export {};

package/dist/schemas/contribution-candidate.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+export declare const CONTRIBUTION_CANDIDATE_SCHEMA_VERSION: "jinn.contribution-candidate.v1";
+/**
+ * The complete local input to contribution mining. Timestamps are required
+ * caller inputs so assembling or parsing a candidate never reads the clock.
+ */
+export declare const ContributionCandidateV1Schema: z.ZodObject<{
+    testRuns: z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        exitCode: z.ZodNumber;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    skillEvents: z.ZodArray<z.ZodObject<{
+        skillRef: z.ZodString;
+        action: z.ZodEnum<{
+            loaded: "loaded";
+            invoked: "invoked";
+        }>;
+    }, z.core.$strict>>;
+    schemaVersion: z.ZodLiteral<"jinn.contribution-candidate.v1">;
+    sourceId: z.ZodString;
+    repositorySlug: z.ZodString;
+    baseCommit: z.ZodString;
+    acceptedDiff: z.ZodString;
+    intermediateFailureDiffs: z.ZodArray<z.ZodString>;
+    publishMinedTasksConsent: z.ZodBoolean;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+/** Additive reader used only inside canonical local EpisodeV1 records. */
+export declare const ContributionCandidateV1ReadSchema: z.ZodObject<{
+    testRuns: z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        exitCode: z.ZodNumber;
+        at: z.ZodISODateTime;
+    }, z.core.$loose>>;
+    skillEvents: z.ZodArray<z.ZodObject<{
+        skillRef: z.ZodString;
+        action: z.ZodEnum<{
+            loaded: "loaded";
+            invoked: "invoked";
+        }>;
+    }, z.core.$loose>>;
+    schemaVersion: z.ZodLiteral<"jinn.contribution-candidate.v1">;
+    sourceId: z.ZodString;
+    repositorySlug: z.ZodString;
+    baseCommit: z.ZodString;
+    acceptedDiff: z.ZodString;
+    intermediateFailureDiffs: z.ZodArray<z.ZodString>;
+    publishMinedTasksConsent: z.ZodBoolean;
+    createdAt: z.ZodISODateTime;
+}, z.core.$loose>;
+export type ContributionCandidateV1 = z.infer<typeof ContributionCandidateV1Schema>;
+/** Resolve a forward-additive candidate from a canonical Episode into the
+ * current v1 fields. Unknown future fields stay in the Episode but never make
+ * an otherwise valid local reference look unresolved to an older reader. */
+export declare const ContributionCandidateV1ProjectionSchema: z.ZodPipe<z.ZodObject<{
+    testRuns: z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        exitCode: z.ZodNumber;
+        at: z.ZodISODateTime;
+    }, z.core.$loose>>;
+    skillEvents: z.ZodArray<z.ZodObject<{
+        skillRef: z.ZodString;
+        action: z.ZodEnum<{
+            loaded: "loaded";
+            invoked: "invoked";
+        }>;
+    }, z.core.$loose>>;
+    schemaVersion: z.ZodLiteral<"jinn.contribution-candidate.v1">;
+    sourceId: z.ZodString;
+    repositorySlug: z.ZodString;
+    baseCommit: z.ZodString;
+    acceptedDiff: z.ZodString;
+    intermediateFailureDiffs: z.ZodArray<z.ZodString>;
+    publishMinedTasksConsent: z.ZodBoolean;
+    createdAt: z.ZodISODateTime;
+}, z.core.$loose>, z.ZodTransform<{
+    testRuns: {
+        command: string;
+        exitCode: number;
+        at: string;
+    }[];
+    skillEvents: {
+        skillRef: string;
+        action: "loaded" | "invoked";
+    }[];
+    schemaVersion: "jinn.contribution-candidate.v1";
+    sourceId: string;
+    repositorySlug: string;
+    baseCommit: string;
+    acceptedDiff: string;
+    intermediateFailureDiffs: string[];
+    publishMinedTasksConsent: boolean;
+    createdAt: string;
+}, {
+    [x: string]: unknown;
+    testRuns: {
+        [x: string]: unknown;
+        command: string;
+        exitCode: number;
+        at: string;
+    }[];
+    skillEvents: {
+        [x: string]: unknown;
+        skillRef: string;
+        action: "loaded" | "invoked";
+    }[];
+    schemaVersion: "jinn.contribution-candidate.v1";
+    sourceId: string;
+    repositorySlug: string;
+    baseCommit: string;
+    acceptedDiff: string;
+    intermediateFailureDiffs: string[];
+    publishMinedTasksConsent: boolean;
+    createdAt: string;
+}>>;

package/dist/schemas/contribution-candidate.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+export const CONTRIBUTION_CANDIDATE_SCHEMA_VERSION = 'jinn.contribution-candidate.v1';
+const ContributionTestRunShape = {
+    command: z.string().min(1),
+    exitCode: z.number().int(),
+    at: z.iso.datetime(),
+};
+const ContributionTestRunSchema = z.strictObject(ContributionTestRunShape);
+const ContributionTestRunReadSchema = z.looseObject(ContributionTestRunShape);
+const ContributionSkillEventShape = {
+    skillRef: z.string().min(1),
+    action: z.enum(['loaded', 'invoked']),
+};
+const ContributionSkillEventSchema = z.strictObject(ContributionSkillEventShape);
+const ContributionSkillEventReadSchema = z.looseObject(ContributionSkillEventShape);
+const ContributionCandidateShape = {
+    schemaVersion: z.literal(CONTRIBUTION_CANDIDATE_SCHEMA_VERSION),
+    sourceId: z.string().min(1),
+    repositorySlug: z.string().min(1),
+    baseCommit: z.string().min(1),
+    acceptedDiff: z.string().min(1),
+    intermediateFailureDiffs: z.array(z.string().min(1)),
+    publishMinedTasksConsent: z.boolean(),
+    createdAt: z.iso.datetime(),
+};
+/**
+ * The complete local input to contribution mining. Timestamps are required
+ * caller inputs so assembling or parsing a candidate never reads the clock.
+ */
+export const ContributionCandidateV1Schema = z.strictObject({
+    ...ContributionCandidateShape,
+    testRuns: z.array(ContributionTestRunSchema),
+    skillEvents: z.array(ContributionSkillEventSchema),
+});
+/** Additive reader used only inside canonical local EpisodeV1 records. */
+export const ContributionCandidateV1ReadSchema = z.looseObject({
+    ...ContributionCandidateShape,
+    testRuns: z.array(ContributionTestRunReadSchema),
+    skillEvents: z.array(ContributionSkillEventReadSchema),
+});
+/** Resolve a forward-additive candidate from a canonical Episode into the
+ * current v1 fields. Unknown future fields stay in the Episode but never make
+ * an otherwise valid local reference look unresolved to an older reader. */
+export const ContributionCandidateV1ProjectionSchema = ContributionCandidateV1ReadSchema
+    .transform((candidate) => ({
+    schemaVersion: candidate.schemaVersion,
+    sourceId: candidate.sourceId,
+    repositorySlug: candidate.repositorySlug,
+    baseCommit: candidate.baseCommit,
+    acceptedDiff: candidate.acceptedDiff,
+    testRuns: candidate.testRuns.map((run) => ({
+        command: run.command,
+        exitCode: run.exitCode,
+        at: run.at,
+    })),
+    intermediateFailureDiffs: candidate.intermediateFailureDiffs,
+    skillEvents: candidate.skillEvents.map((event) => ({
+        skillRef: event.skillRef,
+        action: event.action,
+    })),
+    publishMinedTasksConsent: candidate.publishMinedTasksConsent,
+    createdAt: candidate.createdAt,
+}));

package/dist/schemas/eligibility-verdict.d.ts

@@ -0,0 +1,8 @@
+/** Cheap candidate verdict (architecture spec §5). Authoritative validation is sidecar-side. */
+import { z } from 'zod';
+export declare const EligibilityVerdictSchema: z.ZodObject<{
+    eligible: z.ZodBoolean;
+    reason: z.ZodString;
+    checkedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type EligibilityVerdict = z.infer<typeof EligibilityVerdictSchema>;

package/dist/schemas/eligibility-verdict.js

@@ -0,0 +1,7 @@
+/** Cheap candidate verdict (architecture spec §5). Authoritative validation is sidecar-side. */
+import { z } from 'zod';
+export const EligibilityVerdictSchema = z.strictObject({
+    eligible: z.boolean(),
+    reason: z.string().min(1),
+    checkedAt: z.iso.datetime(),
+});