@jinn-network/core 0.1.0

package/dist/session-provenance.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod/v3';
+export declare const SessionProvenanceSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    capturedAt: z.ZodString;
+    originatingTool: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version?: string | undefined;
+    }, {
+        name: string;
+        version?: string | undefined;
+    }>;
+    repo: z.ZodOptional<z.ZodObject<{
+        remoteUrl: z.ZodOptional<z.ZodString>;
+        commitHash: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        remoteUrl?: string | undefined;
+        commitHash?: string | undefined;
+        branch?: string | undefined;
+    }, {
+        remoteUrl?: string | undefined;
+        commitHash?: string | undefined;
+        branch?: string | undefined;
+    }>>;
+    license: z.ZodObject<{
+        spdxId: z.ZodOptional<z.ZodString>;
+        operatorAssertion: z.ZodEnum<["asserted", "unspecified"]>;
+    }, "strip", z.ZodTypeAny, {
+        operatorAssertion: "asserted" | "unspecified";
+        spdxId?: string | undefined;
+    }, {
+        operatorAssertion: "asserted" | "unspecified";
+        spdxId?: string | undefined;
+    }>;
+    /** The single `share` consent (mono#1714): may a mined task be published. */
+    publishMinedTasksConsent: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    capturedAt: string;
+    originatingTool: {
+        name: string;
+        version?: string | undefined;
+    };
+    license: {
+        operatorAssertion: "asserted" | "unspecified";
+        spdxId?: string | undefined;
+    };
+    publishMinedTasksConsent?: boolean | undefined;
+    repo?: {
+        remoteUrl?: string | undefined;
+        commitHash?: string | undefined;
+        branch?: string | undefined;
+    } | undefined;
+}, {
+    sessionId: string;
+    capturedAt: string;
+    originatingTool: {
+        name: string;
+        version?: string | undefined;
+    };
+    license: {
+        operatorAssertion: "asserted" | "unspecified";
+        spdxId?: string | undefined;
+    };
+    publishMinedTasksConsent?: boolean | undefined;
+    repo?: {
+        remoteUrl?: string | undefined;
+        commitHash?: string | undefined;
+        branch?: string | undefined;
+    } | undefined;
+}>;
+export type SessionProvenance = z.infer<typeof SessionProvenanceSchema>;

package/dist/session-provenance.js

@@ -0,0 +1,20 @@
+import { z } from 'zod/v3';
+export const SessionProvenanceSchema = z.object({
+    sessionId: z.string().min(1),
+    capturedAt: z.string().datetime(),
+    originatingTool: z.object({
+        name: z.string(),
+        version: z.string().optional(),
+    }),
+    repo: z.object({
+        remoteUrl: z.string().optional(),
+        commitHash: z.string().regex(/^[0-9a-f]{40}$/).optional(),
+        branch: z.string().optional(),
+    }).optional(),
+    license: z.object({
+        spdxId: z.string().optional(),
+        operatorAssertion: z.enum(['asserted', 'unspecified']),
+    }),
+    /** The single `share` consent (mono#1714): may a mined task be published. */
+    publishMinedTasksConsent: z.boolean().optional(),
+});

package/dist/skill-artifact.d.ts

@@ -0,0 +1,442 @@
+import { z } from 'zod/v3';
+/**
+ * jinn.skill.v1 — first-class skill artifact (issue #1394).
+ *
+ * A skill (SKILL.md + optional companion files + machine-readable
+ * provenance) carried as one entry in the `jinn.execution.v1` wrapper
+ * envelope's `artifacts[]`. Carrier invariant by provenance kind:
+ * **imported** (seeds) publish ALONGSIDE the seeded layer-1 trace envelope
+ * (never instead of it); **distilled** skills have no trace of their own —
+ * their evidence is the referenced layer-1 envelopes in `sourceEnvelopeCids` —
+ * so they publish as a skill-only wrapper (`publishSkill()`,
+ * packages/layer/src/publish-skill.ts, DR-2026-07-06).
+ * Access/pricing come from the enclosing Artifact
+ * entry (client/src/types/envelope.ts ArtifactSchema: sha256,
+ * access.endpoint, access.priceUsdc, metadata.tags).
+ *
+ * Frozen-caps review (AC3, additive): this schema is a NEW artifact payload
+ * type. It does not touch the frozen layer-1 evidence envelope
+ * (jinn.trace-envelope.v0 — packages/core/src/envelope.ts,
+ * caps in packages/layer/docs/envelope-v0.md) and requires no
+ * change to the jinn.execution.v1 wrapper, whose artifacts[] already accepts
+ * any artifactType string. Companion-file content lives here, free of the
+ * trace envelope's 16 KiB step-attribute cap, under its own 1 MiB total cap.
+ *
+ * Precedent: client/src/trajectory/harness-bundle-schema.ts.
+ */
+export declare const SKILL_ARTIFACT_TYPE: "jinn.skill.v1";
+/** Max companion files per skill. */
+export declare const MAX_SKILL_FILES = 64;
+/** Max total decoded bytes (skillMd + all companion files): 1 MiB. */
+export declare const MAX_SKILL_TOTAL_DECODED_BYTES: number;
+export declare const SkillCompanionFileSchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodString, string, string>;
+    contentBase64: z.ZodString;
+    sha256: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    sha256: string;
+    contentBase64: string;
+}, {
+    path: string;
+    sha256: string;
+    contentBase64: string;
+}>;
+export declare const SkillProvenanceSchema: z.ZodObject<{
+    kind: z.ZodEnum<["imported", "distilled"]>;
+    /**
+     * Envelope CIDs the skill was distilled from ([] for seed imports).
+     * The "distilled from N traces" count is this array's length — never
+     * stored separately (anti-drift).
+     */
+    sourceEnvelopeCids: z.ZodArray<z.ZodString, "many">;
+    operator: z.ZodObject<{
+        safeAddress: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        safeAddress: string;
+    }, {
+        safeAddress: string;
+    }>;
+    solverType: z.ZodOptional<z.ZodString>;
+    /** Seed attribution, mirroring the seeded trace's `seed.attribution`. */
+    seed: z.ZodOptional<z.ZodObject<{
+        skill: z.ZodString;
+        source: z.ZodString;
+        licence: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        skill: string;
+        licence: string | null;
+    }, {
+        source: string;
+        skill: string;
+        licence: string | null;
+    }>>;
+    /**
+     * Success→strategic-pattern, failure→lesson, both-polarity→contrastive
+     * (spec §7, D10 + v0.5), or cross-instance corroboration→cross-instance
+     * (stage-2 meta-distill). `contrastive` and `cross-instance` are additive
+     * enum values: strict consumers (`extractSkill`) reject them until upgraded
+     * — acceptable at testnet volume, named in the spec.
+     */
+    skillKind: z.ZodOptional<z.ZodEnum<["strategic-pattern", "failure-lesson", "contrastive", "cross-instance"]>>;
+    /** SHA-256 of the exact distill prompt that produced the skill (auditability, D4). */
+    distillPromptSha256: z.ZodOptional<z.ZodString>;
+    /** Task-distribution the skill targets (e.g. 'coding'). */
+    distribution: z.ZodOptional<z.ZodString>;
+    /** Verifiability tier of the source evidence (e.g. 'evaluator-verified'). */
+    verifiabilityTier: z.ZodOptional<z.ZodString>;
+    /**
+     * The model that ran distillation (spec §5, v0.5). Distillation quality is
+     * model-sensitive; recording it makes a skill's quality auditable.
+     */
+    distillModel: z.ZodOptional<z.ZodString>;
+    /**
+     * Deterministic `ceil(utf8 chars / 4)` token estimates of the distiller
+     * input and the emitted body (spec §5, v0.5). The pair records the
+     * compression ratio (SkillRL operates at 10–20×); an auditable estimate
+     * serves that purpose better than an unreproducible exact count (the LLM
+     * port reports no usage).
+     */
+    evidenceTokens: z.ZodOptional<z.ZodNumber>;
+    skillTokens: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Envelope/manifest CID of a prior skill record this one replaces — the same
+     * identity space as `sourceEnvelopeCids` and a search-hit `ref`. Honored at
+     * read time ONLY when this record's operator matches the superseded record's
+     * operator (cross-operator supersedes are ignored); see the read-path head
+     * resolver in packages/layer/src/consume.ts.
+     */
+    supersedes: z.ZodOptional<z.ZodString>;
+    /**
+     * Pure retirement marker: retires this record's `supersedes` target with no
+     * replacement and hides this record itself from discovery. A deprecation
+     * record carries no successor skill content.
+     */
+    deprecates: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    kind: "imported" | "distilled";
+    sourceEnvelopeCids: string[];
+    operator: {
+        safeAddress: string;
+    };
+    verifiabilityTier?: string | undefined;
+    solverType?: string | undefined;
+    seed?: {
+        source: string;
+        skill: string;
+        licence: string | null;
+    } | undefined;
+    skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+    distillPromptSha256?: string | undefined;
+    distribution?: string | undefined;
+    distillModel?: string | undefined;
+    evidenceTokens?: number | undefined;
+    skillTokens?: number | undefined;
+    supersedes?: string | undefined;
+    deprecates?: boolean | undefined;
+}, {
+    kind: "imported" | "distilled";
+    sourceEnvelopeCids: string[];
+    operator: {
+        safeAddress: string;
+    };
+    verifiabilityTier?: string | undefined;
+    solverType?: string | undefined;
+    seed?: {
+        source: string;
+        skill: string;
+        licence: string | null;
+    } | undefined;
+    skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+    distillPromptSha256?: string | undefined;
+    distribution?: string | undefined;
+    distillModel?: string | undefined;
+    evidenceTokens?: number | undefined;
+    skillTokens?: number | undefined;
+    supersedes?: string | undefined;
+    deprecates?: boolean | undefined;
+}>;
+export declare const SkillArtifactV1Schema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"jinn.skill.v1">;
+    skill: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        skillMd: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        skillMd: string;
+        description?: string | undefined;
+    }, {
+        name: string;
+        skillMd: string;
+        description?: string | undefined;
+    }>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodEffects<z.ZodString, string, string>;
+        contentBase64: z.ZodString;
+        sha256: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        sha256: string;
+        contentBase64: string;
+    }, {
+        path: string;
+        sha256: string;
+        contentBase64: string;
+    }>, "many">;
+    provenance: z.ZodObject<{
+        kind: z.ZodEnum<["imported", "distilled"]>;
+        /**
+         * Envelope CIDs the skill was distilled from ([] for seed imports).
+         * The "distilled from N traces" count is this array's length — never
+         * stored separately (anti-drift).
+         */
+        sourceEnvelopeCids: z.ZodArray<z.ZodString, "many">;
+        operator: z.ZodObject<{
+            safeAddress: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            safeAddress: string;
+        }, {
+            safeAddress: string;
+        }>;
+        solverType: z.ZodOptional<z.ZodString>;
+        /** Seed attribution, mirroring the seeded trace's `seed.attribution`. */
+        seed: z.ZodOptional<z.ZodObject<{
+            skill: z.ZodString;
+            source: z.ZodString;
+            licence: z.ZodNullable<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            source: string;
+            skill: string;
+            licence: string | null;
+        }, {
+            source: string;
+            skill: string;
+            licence: string | null;
+        }>>;
+        /**
+         * Success→strategic-pattern, failure→lesson, both-polarity→contrastive
+         * (spec §7, D10 + v0.5), or cross-instance corroboration→cross-instance
+         * (stage-2 meta-distill). `contrastive` and `cross-instance` are additive
+         * enum values: strict consumers (`extractSkill`) reject them until upgraded
+         * — acceptable at testnet volume, named in the spec.
+         */
+        skillKind: z.ZodOptional<z.ZodEnum<["strategic-pattern", "failure-lesson", "contrastive", "cross-instance"]>>;
+        /** SHA-256 of the exact distill prompt that produced the skill (auditability, D4). */
+        distillPromptSha256: z.ZodOptional<z.ZodString>;
+        /** Task-distribution the skill targets (e.g. 'coding'). */
+        distribution: z.ZodOptional<z.ZodString>;
+        /** Verifiability tier of the source evidence (e.g. 'evaluator-verified'). */
+        verifiabilityTier: z.ZodOptional<z.ZodString>;
+        /**
+         * The model that ran distillation (spec §5, v0.5). Distillation quality is
+         * model-sensitive; recording it makes a skill's quality auditable.
+         */
+        distillModel: z.ZodOptional<z.ZodString>;
+        /**
+         * Deterministic `ceil(utf8 chars / 4)` token estimates of the distiller
+         * input and the emitted body (spec §5, v0.5). The pair records the
+         * compression ratio (SkillRL operates at 10–20×); an auditable estimate
+         * serves that purpose better than an unreproducible exact count (the LLM
+         * port reports no usage).
+         */
+        evidenceTokens: z.ZodOptional<z.ZodNumber>;
+        skillTokens: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Envelope/manifest CID of a prior skill record this one replaces — the same
+         * identity space as `sourceEnvelopeCids` and a search-hit `ref`. Honored at
+         * read time ONLY when this record's operator matches the superseded record's
+         * operator (cross-operator supersedes are ignored); see the read-path head
+         * resolver in packages/layer/src/consume.ts.
+         */
+        supersedes: z.ZodOptional<z.ZodString>;
+        /**
+         * Pure retirement marker: retires this record's `supersedes` target with no
+         * replacement and hides this record itself from discovery. A deprecation
+         * record carries no successor skill content.
+         */
+        deprecates: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "imported" | "distilled";
+        sourceEnvelopeCids: string[];
+        operator: {
+            safeAddress: string;
+        };
+        verifiabilityTier?: string | undefined;
+        solverType?: string | undefined;
+        seed?: {
+            source: string;
+            skill: string;
+            licence: string | null;
+        } | undefined;
+        skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+        distillPromptSha256?: string | undefined;
+        distribution?: string | undefined;
+        distillModel?: string | undefined;
+        evidenceTokens?: number | undefined;
+        skillTokens?: number | undefined;
+        supersedes?: string | undefined;
+        deprecates?: boolean | undefined;
+    }, {
+        kind: "imported" | "distilled";
+        sourceEnvelopeCids: string[];
+        operator: {
+            safeAddress: string;
+        };
+        verifiabilityTier?: string | undefined;
+        solverType?: string | undefined;
+        seed?: {
+            source: string;
+            skill: string;
+            licence: string | null;
+        } | undefined;
+        skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+        distillPromptSha256?: string | undefined;
+        distribution?: string | undefined;
+        distillModel?: string | undefined;
+        evidenceTokens?: number | undefined;
+        skillTokens?: number | undefined;
+        supersedes?: string | undefined;
+        deprecates?: boolean | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: "jinn.skill.v1";
+    provenance: {
+        kind: "imported" | "distilled";
+        sourceEnvelopeCids: string[];
+        operator: {
+            safeAddress: string;
+        };
+        verifiabilityTier?: string | undefined;
+        solverType?: string | undefined;
+        seed?: {
+            source: string;
+            skill: string;
+            licence: string | null;
+        } | undefined;
+        skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+        distillPromptSha256?: string | undefined;
+        distribution?: string | undefined;
+        distillModel?: string | undefined;
+        evidenceTokens?: number | undefined;
+        skillTokens?: number | undefined;
+        supersedes?: string | undefined;
+        deprecates?: boolean | undefined;
+    };
+    skill: {
+        name: string;
+        skillMd: string;
+        description?: string | undefined;
+    };
+    files: {
+        path: string;
+        sha256: string;
+        contentBase64: string;
+    }[];
+}, {
+    schemaVersion: "jinn.skill.v1";
+    provenance: {
+        kind: "imported" | "distilled";
+        sourceEnvelopeCids: string[];
+        operator: {
+            safeAddress: string;
+        };
+        verifiabilityTier?: string | undefined;
+        solverType?: string | undefined;
+        seed?: {
+            source: string;
+            skill: string;
+            licence: string | null;
+        } | undefined;
+        skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+        distillPromptSha256?: string | undefined;
+        distribution?: string | undefined;
+        distillModel?: string | undefined;
+        evidenceTokens?: number | undefined;
+        skillTokens?: number | undefined;
+        supersedes?: string | undefined;
+        deprecates?: boolean | undefined;
+    };
+    skill: {
+        name: string;
+        skillMd: string;
+        description?: string | undefined;
+    };
+    files: {
+        path: string;
+        sha256: string;
+        contentBase64: string;
+    }[];
+}>, {
+    schemaVersion: "jinn.skill.v1";
+    provenance: {
+        kind: "imported" | "distilled";
+        sourceEnvelopeCids: string[];
+        operator: {
+            safeAddress: string;
+        };
+        verifiabilityTier?: string | undefined;
+        solverType?: string | undefined;
+        seed?: {
+            source: string;
+            skill: string;
+            licence: string | null;
+        } | undefined;
+        skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+        distillPromptSha256?: string | undefined;
+        distribution?: string | undefined;
+        distillModel?: string | undefined;
+        evidenceTokens?: number | undefined;
+        skillTokens?: number | undefined;
+        supersedes?: string | undefined;
+        deprecates?: boolean | undefined;
+    };
+    skill: {
+        name: string;
+        skillMd: string;
+        description?: string | undefined;
+    };
+    files: {
+        path: string;
+        sha256: string;
+        contentBase64: string;
+    }[];
+}, {
+    schemaVersion: "jinn.skill.v1";
+    provenance: {
+        kind: "imported" | "distilled";
+        sourceEnvelopeCids: string[];
+        operator: {
+            safeAddress: string;
+        };
+        verifiabilityTier?: string | undefined;
+        solverType?: string | undefined;
+        seed?: {
+            source: string;
+            skill: string;
+            licence: string | null;
+        } | undefined;
+        skillKind?: "strategic-pattern" | "failure-lesson" | "contrastive" | "cross-instance" | undefined;
+        distillPromptSha256?: string | undefined;
+        distribution?: string | undefined;
+        distillModel?: string | undefined;
+        evidenceTokens?: number | undefined;
+        skillTokens?: number | undefined;
+        supersedes?: string | undefined;
+        deprecates?: boolean | undefined;
+    };
+    skill: {
+        name: string;
+        skillMd: string;
+        description?: string | undefined;
+    };
+    files: {
+        path: string;
+        sha256: string;
+        contentBase64: string;
+    }[];
+}>;
+export type SkillCompanionFile = z.infer<typeof SkillCompanionFileSchema>;
+export type SkillProvenance = z.infer<typeof SkillProvenanceSchema>;
+export type SkillArtifactV1 = z.infer<typeof SkillArtifactV1Schema>;

package/dist/skill-artifact.js

@@ -0,0 +1,136 @@
+import { z } from 'zod/v3';
+/**
+ * jinn.skill.v1 — first-class skill artifact (issue #1394).
+ *
+ * A skill (SKILL.md + optional companion files + machine-readable
+ * provenance) carried as one entry in the `jinn.execution.v1` wrapper
+ * envelope's `artifacts[]`. Carrier invariant by provenance kind:
+ * **imported** (seeds) publish ALONGSIDE the seeded layer-1 trace envelope
+ * (never instead of it); **distilled** skills have no trace of their own —
+ * their evidence is the referenced layer-1 envelopes in `sourceEnvelopeCids` —
+ * so they publish as a skill-only wrapper (`publishSkill()`,
+ * packages/layer/src/publish-skill.ts, DR-2026-07-06).
+ * Access/pricing come from the enclosing Artifact
+ * entry (client/src/types/envelope.ts ArtifactSchema: sha256,
+ * access.endpoint, access.priceUsdc, metadata.tags).
+ *
+ * Frozen-caps review (AC3, additive): this schema is a NEW artifact payload
+ * type. It does not touch the frozen layer-1 evidence envelope
+ * (jinn.trace-envelope.v0 — packages/core/src/envelope.ts,
+ * caps in packages/layer/docs/envelope-v0.md) and requires no
+ * change to the jinn.execution.v1 wrapper, whose artifacts[] already accepts
+ * any artifactType string. Companion-file content lives here, free of the
+ * trace envelope's 16 KiB step-attribute cap, under its own 1 MiB total cap.
+ *
+ * Precedent: client/src/trajectory/harness-bundle-schema.ts.
+ */
+export const SKILL_ARTIFACT_TYPE = 'jinn.skill.v1';
+/** Max companion files per skill. */
+export const MAX_SKILL_FILES = 64;
+/** Max total decoded bytes (skillMd + all companion files): 1 MiB. */
+export const MAX_SKILL_TOTAL_DECODED_BYTES = 1024 * 1024;
+const HexAddressSchema = z.string().regex(/^0x[0-9a-fA-F]*$/);
+/**
+ * Relative, traversal-free POSIX path — this is written to disk on install.
+ * Backslashes are rejected outright: on Windows `path.join` treats `\` as a
+ * separator, so a `..\` segment would bypass the '/'-split traversal check.
+ */
+const CompanionPathSchema = z
+    .string()
+    .min(1)
+    .refine((p) => !p.includes('\\') &&
+    !p.startsWith('/') &&
+    !/^[A-Za-z]:/.test(p) &&
+    !p.split('/').includes('..') &&
+    !p.split('/').includes(''), { message: 'companion file path must be a relative, traversal-free POSIX path' });
+export const SkillCompanionFileSchema = z.object({
+    path: CompanionPathSchema,
+    contentBase64: z.string(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export const SkillProvenanceSchema = z.object({
+    kind: z.enum(['imported', 'distilled']),
+    /**
+     * Envelope CIDs the skill was distilled from ([] for seed imports).
+     * The "distilled from N traces" count is this array's length — never
+     * stored separately (anti-drift).
+     */
+    sourceEnvelopeCids: z.array(z.string().min(1)),
+    operator: z.object({ safeAddress: HexAddressSchema }),
+    solverType: z.string().min(1).optional(),
+    /** Seed attribution, mirroring the seeded trace's `seed.attribution`. */
+    seed: z
+        .object({
+        skill: z.string().min(1),
+        source: z.string().min(1),
+        licence: z.string().nullable(),
+    })
+        .optional(),
+    // --- distilled-skill fields (DR-2026-07-06, additive; producer is
+    // publishSkill() in packages/layer/src/publish-skill.ts) ---
+    /**
+     * Success→strategic-pattern, failure→lesson, both-polarity→contrastive
+     * (spec §7, D10 + v0.5), or cross-instance corroboration→cross-instance
+     * (stage-2 meta-distill). `contrastive` and `cross-instance` are additive
+     * enum values: strict consumers (`extractSkill`) reject them until upgraded
+     * — acceptable at testnet volume, named in the spec.
+     */
+    skillKind: z.enum(['strategic-pattern', 'failure-lesson', 'contrastive', 'cross-instance']).optional(),
+    /** SHA-256 of the exact distill prompt that produced the skill (auditability, D4). */
+    distillPromptSha256: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+    /** Task-distribution the skill targets (e.g. 'coding'). */
+    distribution: z.string().min(1).optional(),
+    /** Verifiability tier of the source evidence (e.g. 'evaluator-verified'). */
+    verifiabilityTier: z.string().min(1).optional(),
+    /**
+     * The model that ran distillation (spec §5, v0.5). Distillation quality is
+     * model-sensitive; recording it makes a skill's quality auditable.
+     */
+    distillModel: z.string().min(1).optional(),
+    /**
+     * Deterministic `ceil(utf8 chars / 4)` token estimates of the distiller
+     * input and the emitted body (spec §5, v0.5). The pair records the
+     * compression ratio (SkillRL operates at 10–20×); an auditable estimate
+     * serves that purpose better than an unreproducible exact count (the LLM
+     * port reports no usage).
+     */
+    evidenceTokens: z.number().int().nonnegative().optional(),
+    skillTokens: z.number().int().nonnegative().optional(),
+    // --- supersede lineage (issue #1462, additive) ---
+    /**
+     * Envelope/manifest CID of a prior skill record this one replaces — the same
+     * identity space as `sourceEnvelopeCids` and a search-hit `ref`. Honored at
+     * read time ONLY when this record's operator matches the superseded record's
+     * operator (cross-operator supersedes are ignored); see the read-path head
+     * resolver in packages/layer/src/consume.ts.
+     */
+    supersedes: z.string().min(1).optional(),
+    /**
+     * Pure retirement marker: retires this record's `supersedes` target with no
+     * replacement and hides this record itself from discovery. A deprecation
+     * record carries no successor skill content.
+     */
+    deprecates: z.boolean().optional(),
+});
+/** Decoded size of a base64 string without decoding it. */
+function base64DecodedBytes(b64) {
+    const padding = b64.endsWith('==') ? 2 : b64.endsWith('=') ? 1 : 0;
+    return Math.max(0, Math.floor((b64.length * 3) / 4) - padding);
+}
+export const SkillArtifactV1Schema = z
+    .object({
+    schemaVersion: z.literal(SKILL_ARTIFACT_TYPE),
+    skill: z.object({
+        name: z.string().min(1),
+        description: z.string().optional(),
+        skillMd: z.string().min(1),
+    }),
+    files: z.array(SkillCompanionFileSchema).max(MAX_SKILL_FILES),
+    provenance: SkillProvenanceSchema,
+})
+    .refine((a) => new TextEncoder().encode(a.skill.skillMd).length +
+    a.files.reduce((n, f) => n + base64DecodedBytes(f.contentBase64), 0) <=
+    MAX_SKILL_TOTAL_DECODED_BYTES, { message: 'skill artifact exceeds the 1 MiB total decoded-content cap' });

package/dist/trajectory/hash-chain.d.ts

@@ -0,0 +1,18 @@
+/**
+ * In-run per-span hash chain.
+ *
+ * Scope: §3.1 trajectory-signing-granularity row — "each span carries
+ * jinn.prevSpanHash linking to the previous span's hash; first span
+ * links to a run-start genesis value derived from envelope task CID."
+ *
+ * Motivation: a crashed run that failed to upload the signed trajectory
+ * blob still produces a verifiable-as-prefix trace if spans are recovered
+ * elsewhere (enclave memory dump, challenger capture). Partial authenticity
+ * is not zero.
+ */
+import type { Span } from './schema.js';
+export type Hex = `0x${string}`;
+/** Genesis value for the chain — keccak256(JCS({runStart: taskCid})). */
+export declare function computeGenesisHash(taskCid: string): Hex;
+/** Hash of a finalized span, to be set as jinn.prevSpanHash on the next one. */
+export declare function computePrevSpanHash(span: Span): Hex;