@jinn-network/core 0.1.0

package/dist/canonical-json.d.ts

@@ -0,0 +1 @@
+export declare function canonicalJson(value: unknown): string;

package/dist/canonical-json.js

@@ -0,0 +1,67 @@
+/**
+ * Canonical JSON serialisation — RFC 8785 JCS.
+ *
+ * Uses the `canonicalize` npm package (≈30 LOC, zero deps) so third-party
+ * verifiers can reproduce our signing input with any standard JCS library.
+ *
+ * Rules per RFC 8785:
+ * - Object keys sorted lexicographically by UTF-16 code-unit order.
+ * - No insignificant whitespace.
+ * - I-JSON number formatting per ECMAScript `Number.prototype.toString(10)`
+ *   (integer-preferred; scientific notation when |x| ≥ 1e21 or |x| < 5e-7;
+ *   -0 serialises as 0).
+ * - String escape rules per JSON spec (control chars as \\uXXXX; only ", \
+ *   and control chars must be escaped).
+ * - `undefined` values in objects are dropped (matches JSON.stringify).
+ * - `NaN` / `Infinity` serialise to `null` (matches JSON.stringify).
+ *
+ * BigInt is **not** supported — JCS is a canonicalization of standard JSON,
+ * which has no BigInt type. Callers must convert BigInt to string or number
+ * before calling. Passing BigInt throws.
+ *
+ * Used for manifest signing: produce a deterministic byte string that two
+ * independent parties can reproduce from the same object graph.
+ */
+// canonicalize v3 is ESM-only (no CJS entry); the client is `"type": "module"`
+// so a native ESM default import is the correct interop (replaces the v2-era
+// createRequire shim). v3 is packaging-only vs v2 — its RFC 8785 output is
+// byte-identical, so existing content hashes / manifest signatures are stable.
+import canonicalize from 'canonicalize';
+/**
+ * Recursively replace NaN / ±Infinity with null so that canonicalize does not
+ * throw — matching the JSON.stringify behaviour that the rest of the codebase
+ * expects. BigInt is intentionally left unhandled so that canonicalize throws
+ * a clear error when a caller passes one.
+ */
+function coerceNonFinite(value) {
+    if (typeof value === 'number' && !isFinite(value))
+        return null;
+    if (Array.isArray(value))
+        return value.map(coerceNonFinite);
+    if (value !== null && typeof value === 'object') {
+        // Preserve toJSON() — canonicalize would otherwise call it itself;
+        // by pre-processing we must not strip it. Invoke it here and recurse
+        // on its return value so NaN/Infinity inside toJSON results are still
+        // coerced.
+        const toJson = value.toJSON;
+        if (typeof toJson === 'function') {
+            return coerceNonFinite(toJson.call(value));
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = coerceNonFinite(v);
+        return out;
+    }
+    return value;
+}
+export function canonicalJson(value) {
+    const coerced = coerceNonFinite(value);
+    const result = canonicalize(coerced);
+    if (result === undefined) {
+        // canonicalize returns undefined for top-level undefined input (matches
+        // JSON.stringify). Match Jinn's previous behaviour: emit "null" so the
+        // return type is always a string.
+        return 'null';
+    }
+    return result;
+}

package/dist/captured-task.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Captured-task schema — the raw, pre-scrub input to the harness capture path.
+ *
+ * Extracted from the former client harness layer in C2 (#1833):
+ * the parse half of capture.ts has no scrub / `client/src` dependency (only
+ * zod + the two envelope enums), so it moved into `@jinn-network/core`.
+ * C5 subsequently moved the scrub implementation alongside it while leaving
+ * capture orchestration in the layer.
+ */
+import { z } from 'zod';
+/**
+ * A captured task — the raw, pre-scrub input to `capture()`. Mirrors the
+ * envelope shape minus `consent` (which does not exist pre-consent) with
+ * UNSCRUBBED step attributes and no size caps (raw captures routinely exceed
+ * them; the fitting rule applies to the conversion output, not the input).
+ * Strict: a task file with unknown fields is malformed, not tolerated.
+ */
+export declare const CapturedTaskSchema: z.ZodObject<{
+    session: z.ZodObject<{
+        sessionId: z.ZodString;
+        capturedAt: z.ZodISODateTime;
+        kind: z.ZodOptional<z.ZodEnum<{
+            user: "user";
+            "host-internal": "host-internal";
+        }>>;
+        parentSessionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    task: z.ZodObject<{
+        summary: z.ZodString;
+        distributionTags: z.ZodArray<z.ZodString>;
+        repositorySlug: z.ZodOptional<z.ZodString>;
+        baseCommit: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodNumber>;
+        instanceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    environment: z.ZodObject<{
+        harness: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        model: z.ZodString;
+        tools: z.ZodArray<z.ZodString>;
+        skillsLoadout: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        generatorModel: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            provider: z.ZodOptional<z.ZodString>;
+            openWeights: z.ZodOptional<z.ZodBoolean>;
+            source: z.ZodEnum<{
+                stream: "stream";
+                config: "config";
+            }>;
+        }, z.core.$strict>>;
+        distributionClass: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            open: "open";
+            "restricted-tos": "restricted-tos";
+        }>>;
+        verifier: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"f2p-p2p">;
+            failToPass: z.ZodArray<z.ZodString>;
+            passToPass: z.ZodArray<z.ZodString>;
+            evalSemanticsVersion: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodEnum<{
+                command: "command";
+                none: "none";
+            }>;
+            failToPass: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            passToPass: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            evalSemanticsVersion: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>;
+    steps: z.ZodArray<z.ZodObject<{
+        spanId: z.ZodString;
+        parentSpanId: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            "jinn.agent_turn": "jinn.agent_turn";
+            "jinn.tool_call": "jinn.tool_call";
+        }>>;
+        startTimeUnixNano: z.ZodString;
+        endTimeUnixNano: z.ZodString;
+        attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        redactedKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            timeUnixNano: z.ZodString;
+            name: z.ZodString;
+            attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>>>;
+        status: z.ZodOptional<z.ZodObject<{
+            code: z.ZodEnum<{
+                UNSET: "UNSET";
+                OK: "OK";
+                ERROR: "ERROR";
+            }>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, 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";
+        }>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    cost: z.ZodObject<{
+        durationMs: z.ZodNumber;
+        tokens: z.ZodOptional<z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+        }, z.core.$strict>>;
+        usdEstimate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    attemptGroup: z.ZodOptional<z.ZodObject<{
+        groupId: z.ZodString;
+        attemptId: z.ZodString;
+        relatedAttemptRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        groupSize: z.ZodOptional<z.ZodNumber>;
+        nPass: z.ZodOptional<z.ZodNumber>;
+        nFail: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    lineage: z.ZodOptional<z.ZodObject<{
+        episodeId: z.ZodString;
+        mintRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    provenance: z.ZodDefault<z.ZodEnum<{
+        contributed: "contributed";
+        imported: "imported";
+        "derived-from-history": "derived-from-history";
+    }>>;
+}, z.core.$strict>;
+export type CapturedTask = z.infer<typeof CapturedTaskSchema>;
+/** Parse an untrusted value (e.g. a task file) as a CapturedTask; throws ZodError. */
+export declare function parseCapturedTask(input: unknown): CapturedTask;

package/dist/captured-task.js

@@ -0,0 +1,122 @@
+/**
+ * Captured-task schema — the raw, pre-scrub input to the harness capture path.
+ *
+ * Extracted from the former client harness layer in C2 (#1833):
+ * the parse half of capture.ts has no scrub / `client/src` dependency (only
+ * zod + the two envelope enums), so it moved into `@jinn-network/core`.
+ * C5 subsequently moved the scrub implementation alongside it while leaving
+ * capture orchestration in the layer.
+ */
+import { z } from 'zod';
+import { EvidenceProvenanceSchema, OutcomeStatusSchema, VerifiabilityTierSchema, } from './envelope.js';
+/** Unix-nanosecond timestamp string (OTel span convention). */
+const UnixNanoSchema = z.string().regex(/^\d+$/, 'unix-nanosecond digit string');
+const F2pP2pVerifierSchema = z.strictObject({
+    type: z.literal('f2p-p2p'),
+    failToPass: z.array(z.string().min(1)),
+    passToPass: z.array(z.string().min(1)),
+    evalSemanticsVersion: z.string().min(1),
+});
+const OtherVerifierSchema = z.strictObject({
+    type: z.enum(['command', 'none']),
+    failToPass: z.array(z.string().min(1)).default([]),
+    passToPass: z.array(z.string().min(1)).default([]),
+    evalSemanticsVersion: z.string().min(1).optional(),
+});
+const CapturedVerifierSchema = z.discriminatedUnion('type', [
+    F2pP2pVerifierSchema,
+    OtherVerifierSchema,
+]);
+const CapturedStepEventSchema = z.strictObject({
+    timeUnixNano: UnixNanoSchema,
+    name: z.string().min(1),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+});
+const CapturedStepStatusSchema = z.strictObject({
+    code: z.enum(['UNSET', 'OK', 'ERROR']),
+    message: z.string().min(1).optional(),
+});
+/**
+ * A captured task — the raw, pre-scrub input to `capture()`. Mirrors the
+ * envelope shape minus `consent` (which does not exist pre-consent) with
+ * UNSCRUBBED step attributes and no size caps (raw captures routinely exceed
+ * them; the fitting rule applies to the conversion output, not the input).
+ * Strict: a task file with unknown fields is malformed, not tolerated.
+ */
+export const CapturedTaskSchema = z.strictObject({
+    session: z.strictObject({
+        sessionId: z.string().min(1).max(128),
+        capturedAt: z.iso.datetime(),
+        kind: z.enum(['user', 'host-internal']).optional(),
+        parentSessionId: z.string().min(1).max(128).optional(),
+    }),
+    task: z.strictObject({
+        summary: z.string().min(1),
+        distributionTags: z.array(z.string().min(1)).min(1),
+        repositorySlug: z.string().min(1).optional(),
+        baseCommit: z.string().min(1).optional(),
+        createdAt: z.number().int().nonnegative().optional(),
+        instanceId: z.string().min(1).optional(),
+    }),
+    environment: z.strictObject({
+        harness: z.strictObject({
+            name: z.string().min(1),
+            version: z.string().min(1),
+        }),
+        model: z.string().min(1),
+        tools: z.array(z.string().min(1)),
+        skillsLoadout: z.array(z.string().min(1)).optional(),
+        generatorModel: z.strictObject({
+            id: z.string().min(1),
+            provider: z.string().min(1).optional(),
+            openWeights: z.boolean().optional(),
+            source: z.enum(['stream', 'config']),
+        }).optional(),
+        distributionClass: z.enum(['open', 'restricted-tos', 'unknown']).optional(),
+        verifier: CapturedVerifierSchema.optional(),
+    }),
+    steps: z.array(z.strictObject({
+        spanId: z.string().min(1),
+        parentSpanId: z.string().min(1).nullable(),
+        name: z.string().min(1),
+        kind: z.enum(['jinn.agent_turn', 'jinn.tool_call']).optional(),
+        startTimeUnixNano: UnixNanoSchema,
+        endTimeUnixNano: UnixNanoSchema,
+        attributes: z.record(z.string(), z.unknown()),
+        /** Keys already redacted at ingest, if the capture recorded any. */
+        redactedKeys: z.array(z.string().min(1)).default([]),
+        /** Optional canonical OTLP observations retained by richer transcript parsers. */
+        events: z.array(CapturedStepEventSchema).optional(),
+        status: CapturedStepStatusSchema.optional(),
+    })).min(1),
+    outcome: z.strictObject({
+        status: OutcomeStatusSchema,
+        verifiabilityTier: VerifiabilityTierSchema,
+        summary: z.string().min(1).optional(),
+    }),
+    cost: z.strictObject({
+        durationMs: z.number().int().nonnegative(),
+        tokens: z.strictObject({
+            input: z.number().int().nonnegative(),
+            output: z.number().int().nonnegative(),
+        }).optional(),
+        usdEstimate: z.string().regex(/^\d+(\.\d+)?$/).optional(),
+    }),
+    attemptGroup: z.strictObject({
+        groupId: z.string().min(1),
+        attemptId: z.string().min(1),
+        relatedAttemptRefs: z.array(z.string().min(1)).default([]),
+        groupSize: z.number().int().positive().optional(),
+        nPass: z.number().int().nonnegative().optional(),
+        nFail: z.number().int().nonnegative().optional(),
+    }).optional(),
+    lineage: z.strictObject({
+        episodeId: z.string().min(1),
+        mintRef: z.string().min(1).optional(),
+    }).optional(),
+    provenance: EvidenceProvenanceSchema.default('contributed'),
+});
+/** Parse an untrusted value (e.g. a task file) as a CapturedTask; throws ZodError. */
+export function parseCapturedTask(input) {
+    return CapturedTaskSchema.parse(input);
+}

package/dist/contribution-store.d.ts

@@ -0,0 +1,97 @@
+import { type ContributionCandidateV1, type EpisodeV1, type ContributionLocalState, type ContributionPublicationState } from '@jinn-network/plugin';
+export declare const CONTRIBUTION_STORE_SCHEMA_VERSION: "jinn.contribution-store.v3";
+export declare const CONTRIBUTION_STORE_FILE: "mineable-traces.json";
+export declare const CONTRIBUTION_PUBLICATION_DISABLED_FILE: "publication-disabled";
+export declare const CONTRIBUTION_PUBLICATION_SCHEMA_VERSION: "jinn.contribution-publication.v1";
+export declare const DEFAULT_CONTRIBUTION_STATE_DIR: string;
+export declare function resolveContributionStateDir(env?: {
+    JINN_MINEABLE_STATE_DIR?: string;
+}): string;
+export interface ContributionLocalMetadata {
+    /** Compatibility-only task kind; never included in an outbound projection. */
+    kind?: 'solvernet-execution' | 'harness-session';
+    /** Compatibility-only source task reference for second-generation guards. */
+    sourceInstanceId?: string;
+}
+export interface ContributionStoreRecord {
+    recordId: string;
+    localState: ContributionLocalState;
+    publicationState: ContributionPublicationState;
+    mintRef?: string;
+    publicationRef?: string;
+    rejectionReason?: string;
+}
+export interface ContributionPublicationV1 {
+    schemaVersion: typeof CONTRIBUTION_PUBLICATION_SCHEMA_VERSION;
+    repositorySlug: string;
+    baseCommit: string;
+    mintRef: string;
+}
+export interface ContributionStoreLockOptions {
+    retryDelayMs?: number;
+    maxRetries?: number;
+    staleAfterMs?: number;
+}
+export interface ContributionStoreOptions {
+    stateDir?: string;
+    filePath?: string;
+    lock?: ContributionStoreLockOptions;
+    publicationLock?: ContributionStoreLockOptions;
+    /** Lock-clock seam only. Candidate timestamps always come from the caller. */
+    nowMs?: () => number;
+}
+export interface ContributionStoreRecordOptions {
+    publicationState?: 'vetoed';
+}
+export interface ContributionStoreReferenceOptions extends ContributionStoreRecordOptions {
+    /** Transition input only; never serialized in the reference store. */
+    publishMinedTasksConsent?: boolean;
+}
+/**
+ * Cacheless, cross-process-safe contribution store. Every mutation acquires a
+ * mkdir-based lock and performs a fresh read-modify-atomic-rename cycle.
+ */
+export declare class ContributionStore {
+    readonly filePath: string;
+    private readonly lockPath;
+    private readonly publicationLockPath;
+    private readonly publicationDisabledPath;
+    private readonly lock;
+    private readonly publicationLock;
+    private readonly nowMs;
+    constructor(options: ContributionStoreOptions);
+    private tryRecoverStaleLock;
+    private ownerProcessAlive;
+    private recoveryOwnerName;
+    private recoveryOwnerMetadata;
+    private acquireRecoveryGuard;
+    private acquireLockAt;
+    private withLockAt;
+    private withLock;
+    private withPublicationLock;
+    private writeAtomic;
+    private preserveMigrationBackup;
+    private loadUnlocked;
+    private mutate;
+    private publicationDisabledUnlocked;
+    record(candidateInput: ContributionCandidateV1, _localMetadata?: ContributionLocalMetadata, options?: ContributionStoreRecordOptions): Promise<ContributionStoreRecord>;
+    recordReference(episodeId: string, options?: ContributionStoreReferenceOptions): Promise<ContributionStoreRecord>;
+    get(recordId: string): Promise<ContributionStoreRecord | undefined>;
+    list(): Promise<ContributionStoreRecord[]>;
+    listRecorded(): Promise<ContributionStoreRecord[]>;
+    authorize(recordId: string, acknowledgedAt: string): Promise<ContributionStoreRecord>;
+    markMinted(recordId: string, mintRef?: string): Promise<ContributionStoreRecord>;
+    markRejected(recordId: string, reason?: string): Promise<ContributionStoreRecord>;
+    veto(recordId: string): Promise<ContributionStoreRecord>;
+    disableUnpublished(): Promise<string[]>;
+    enablePublication(): Promise<void>;
+    publishAuthorized<T>(recordId: string, operation: () => Promise<{
+        value: T;
+        mintRef: string;
+        publicationRef: string;
+    }>): Promise<T>;
+    markPublished(recordId: string, publicationRef: string): Promise<ContributionStoreRecord>;
+    toOutboundProjection(record: ContributionStoreRecord, episodeInput: EpisodeV1): ContributionPublicationV1;
+    private requireRecord;
+    private throwPublishedImmutable;
+}