@jinn-network/plugin 0.1.0

package/dist/plugin.js

@@ -0,0 +1,586 @@
+/**
+ * Host-neutral Stage 1 product workflow. Embedded hosts buffer their session
+ * through `PluginSession`; process hosts pass the already-captured EpisodeV1
+ * to `completeSession`. Both paths persist the same canonical evidence and
+ * contribution contracts.
+ */
+/// <reference types="node" />
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { EPISODE_SCHEMA_VERSION, EpisodeV1Schema, EpisodeV1WriteSchema, SessionActivityFactsSchema, } from './schemas/episode.js';
+import { ContributionCandidateV1ProjectionSchema, ContributionCandidateV1Schema, } from './schemas/contribution-candidate.js';
+import { projectKnowledgePacket } from './schemas/knowledge-packet.js';
+import { deriveSearchTerms, discriminatingTerms, rankKnowledgeCandidates, rankScoredKnowledgeHits, scoreKnowledgeRecord, MAX_CONTENT_RESCORE_CANDIDATES, MAX_SELECTED_PACKETS, RELEVANCE_FLOOR, } from './pickup.js';
+import { degraded, ok, unavailable, valueOr } from './outcome.js';
+import { parsePickupConfig } from './schemas/pickup-config.js';
+import { deriveEligibility } from './eligibility.js';
+import { foldExplain, foldHistory } from './history.js';
+async function previewContribution(deps, acknowledge) {
+    let ledger;
+    try {
+        ledger = await deps.contribution.ledger();
+    }
+    catch (error) {
+        return unavailable(`contribution preview failed: ${errorReason(error)}`);
+    }
+    if (ledger.status === 'unavailable')
+        return unavailable(ledger.reason);
+    const rows = ledger.status === 'ok' ? ledger.value : ledger.value ?? [];
+    const row = rows.find((entry) => entry.publicationState === 'preview-required');
+    if (!row) {
+        return ledger.status === 'degraded' ? degraded(ledger.reason, null) : ok(null);
+    }
+    if (!row.repositorySlug || !row.baseCommit) {
+        return unavailable('contribution preview repository facts unavailable');
+    }
+    let publicationState = 'preview-required';
+    if (acknowledge) {
+        let authorization;
+        try {
+            authorization = await deps.contribution.authorize(row.recordId);
+        }
+        catch (error) {
+            return unavailable(`contribution preview acknowledgement failed: ${errorReason(error)}`);
+        }
+        if (authorization.status === 'unavailable')
+            return unavailable(authorization.reason);
+        if (authorization.status === 'degraded') {
+            return degraded(authorization.reason);
+        }
+        publicationState = 'queued';
+    }
+    const value = {
+        recordId: row.recordId,
+        repositorySlug: row.repositorySlug,
+        baseCommit: row.baseCommit,
+        localState: row.localState,
+        publicationState,
+        status: publicationState,
+        acknowledged: acknowledge,
+    };
+    return ledger.status === 'degraded' ? degraded(ledger.reason, value) : ok(value);
+}
+export const JINN_PLUGIN_CONTRACT_VERSION = 1;
+function errorReason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Titles for `SessionSummary.providedPackets` — the packet's own task summary. */
+function packetTitle(packet) {
+    return { ref: packet.ref, title: packet.task.summary };
+}
+async function completeSession(deps, input, hits = { providedPackets: [] }) {
+    if (input.contractVersion !== JINN_PLUGIN_CONTRACT_VERSION) {
+        throw new Error(`unsupported plugin contract version: ${String(input.contractVersion)}`);
+    }
+    const capturedEpisode = EpisodeV1Schema.parse(input.episode);
+    const activity = SessionActivityFactsSchema.parse(input.activity);
+    const eligibility = deriveEligibility({
+        status: capturedEpisode.outcome.status,
+        verifiabilityTier: capturedEpisode.outcome.verificationStrength,
+        retentionPolicy: capturedEpisode.retention.policy,
+        publicRepo: input.eligibilityInputs.publicRepo,
+        acceptedDiff: input.eligibilityInputs.acceptedDiff,
+    }, capturedEpisode.session.capturedAt);
+    const embeddedCandidateResult = capturedEpisode.contributionCandidate === undefined
+        ? undefined
+        : ContributionCandidateV1ProjectionSchema.safeParse(capturedEpisode.contributionCandidate);
+    const requestCandidateResult = input.contributionCandidate === undefined
+        ? undefined
+        : ContributionCandidateV1Schema.safeParse(input.contributionCandidate);
+    let resolvedCandidate;
+    let contributionUnavailableReason;
+    if ((capturedEpisode.contributionCandidate !== undefined || input.contributionCandidate !== undefined)
+        && capturedEpisode.session.kind === 'host-internal') {
+        contributionUnavailableReason = 'host-internal sessions cannot create contribution candidates';
+    }
+    else if (embeddedCandidateResult && !embeddedCandidateResult.success) {
+        contributionUnavailableReason = 'invalid embedded contribution candidate';
+    }
+    else if (requestCandidateResult && !requestCandidateResult.success) {
+        contributionUnavailableReason = 'invalid contribution candidate';
+    }
+    else {
+        const embeddedCandidate = embeddedCandidateResult?.data;
+        const requestCandidate = requestCandidateResult?.data;
+        if (embeddedCandidate
+            && requestCandidate
+            && !isDeepStrictEqual(embeddedCandidate, requestCandidate)) {
+            contributionUnavailableReason = 'embedded and request contribution candidates must match';
+        }
+        else {
+            resolvedCandidate = requestCandidate ?? embeddedCandidate;
+            if (resolvedCandidate && resolvedCandidate.sourceId !== capturedEpisode.episodeId) {
+                contributionUnavailableReason = 'contribution candidate sourceId must match episodeId';
+                resolvedCandidate = undefined;
+            }
+        }
+    }
+    // A contribution payload must be present before the first immutable evidence
+    // write. Invalid or forbidden payloads are dropped so the session evidence
+    // itself is still retained.
+    const { contributionCandidate: _capturedCandidate, ...capturedWithoutCandidate } = capturedEpisode;
+    const episode = EpisodeV1WriteSchema.parse({
+        ...capturedWithoutCandidate,
+        session: {
+            ...capturedEpisode.session,
+            kind: capturedEpisode.session.kind ?? 'user',
+        },
+        origin: capturedEpisode.origin === 'legacy-unstamped'
+            ? {
+                writer: capturedEpisode.environment.harness.name,
+                build: capturedEpisode.environment.harness.version,
+            }
+            : capturedEpisode.origin,
+        activity,
+        eligibility,
+        ...(resolvedCandidate ? { contributionCandidate: resolvedCandidate } : {}),
+    });
+    let persistence;
+    try {
+        persistence = await deps.evidence.put(episode);
+    }
+    catch (error) {
+        persistence = unavailable(`evidence put failed: ${errorReason(error)}`);
+    }
+    let contribution;
+    if (contributionUnavailableReason) {
+        contribution = unavailable(contributionUnavailableReason);
+    }
+    else if (resolvedCandidate !== undefined) {
+        const persistedEpisodeId = persistence.status === 'unavailable'
+            ? undefined
+            : persistence.value?.episodeId;
+        if (persistedEpisodeId !== episode.episodeId) {
+            contribution = unavailable('contribution reference not recorded because canonical episode persistence was not confirmed');
+        }
+        else {
+            try {
+                contribution = await deps.contribution.recordMineable(resolvedCandidate, input.contributionVetoed ? { publicationState: 'vetoed' } : undefined);
+            }
+            catch (error) {
+                contribution = unavailable(`contribution record failed: ${errorReason(error)}`);
+            }
+            if (contribution.status === 'ok' && input.contributionVetoed === true) {
+                const recordId = contribution.value.recordId;
+                try {
+                    const veto = await deps.contribution.veto(recordId);
+                    contribution = veto.status === 'unavailable'
+                        ? degraded(veto.reason, { recordId })
+                        : veto;
+                }
+                catch (error) {
+                    contribution = degraded(`contribution veto failed: ${errorReason(error)}`, { recordId });
+                }
+            }
+            else if (contribution.status === 'ok') {
+                const recordId = contribution.value.recordId;
+                try {
+                    const snapshot = await deps.contribution.mintStatus(recordId);
+                    if (snapshot.status === 'ok') {
+                        contribution = ok({ recordId, ...snapshot.value });
+                    }
+                    else if (snapshot.status === 'degraded' && snapshot.value !== undefined) {
+                        contribution = degraded(snapshot.reason, { recordId, ...snapshot.value });
+                    }
+                    else {
+                        contribution = degraded(snapshot.reason, { recordId });
+                    }
+                }
+                catch (error) {
+                    contribution = degraded(`contribution status failed: ${errorReason(error)}`, { recordId });
+                }
+            }
+        }
+    }
+    const providedPackets = hits.providedPackets.length > 0
+        ? hits.providedPackets.map(packetTitle)
+        : activity.providedRefs.map((ref) => ({ ref, title: ref }));
+    const summary = {
+        episodeRef: episode.episodeId,
+        searchedTerms: activity.searchedTerms,
+        providedPackets,
+        eligibility,
+        nothingFound: activity.providedRefs.length === 0,
+    };
+    return {
+        episodeRef: episode.episodeId,
+        persistence,
+        ...(contribution !== undefined ? { contribution } : {}),
+        eligibility,
+        summary,
+    };
+}
+export class PluginSession {
+    deps;
+    meta;
+    trajectory = [];
+    searchedTerms = [];
+    providedRefs = [];
+    fetchedRefs = [];
+    packets = [];
+    retrievalFired = false;
+    eligibleRefs = [];
+    deliveryMode = 'disabled';
+    deliveredContentHash;
+    capturedAt = new Date().toISOString();
+    constructor(deps, meta) {
+        this.deps = deps;
+        this.meta = meta;
+    }
+    async firstTurnPickup(firstMessage) {
+        const config = parsePickupConfig(this.meta.pickup);
+        if (!config.enabled) {
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: [],
+                retrievalFired: false,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveryMode: 'disabled',
+            };
+        }
+        const terms = deriveSearchTerms(firstMessage, this.meta.repositorySlug);
+        // Search with every term; score with the discriminating ones only — the
+        // repository name tags every record in an in-repo corpus, so counting it
+        // halved the effective relevance floor (#1886).
+        const scoringTerms = discriminatingTerms(terms, this.meta.repositorySlug);
+        this.searchedTerms = terms;
+        this.retrievalFired = true;
+        this.deliveryMode = 'delivered';
+        if (terms.length === 0) {
+            this.deliveryMode = 'withheld';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveryMode: this.deliveryMode,
+            };
+        }
+        // Issue all per-term searches concurrently — the searches are
+        // independent (mono #1795: sequential awaits serialized ~1.6s/term of
+        // live indexer round-trips, blowing the 15s host deadline once lexical
+        // v2 widened the term budget to 10). `Promise.all` preserves result
+        // order by term index regardless of resolution order, so the merge
+        // below stays in term order — dedup priority and the first-observed
+        // degraded reason are byte-identical to the old sequential loop. A
+        // rejected promise would violate the PortResult convention (ports
+        // resolve, never throw), but is guarded anyway: it degrades that one
+        // term's contribution rather than the whole pickup (fail-open).
+        const results = await Promise.all(terms.map((term) => this.deps.corpus.search(term).catch((error) => degraded(`corpus search rejected: ${errorReason(error)}`))));
+        // Merge hits in term order (skip non-ok reads → fail open; keep the
+        // first degraded reason observed for an honest, non-crashing report).
+        let degradedReason;
+        const byRef = new Map();
+        for (const result of results) {
+            if (result.status !== 'ok' && degradedReason === undefined)
+                degradedReason = result.reason;
+            for (const hit of valueOr(result, [])) {
+                if (!byRef.has(hit.ref))
+                    byRef.set(hit.ref, hit);
+            }
+        }
+        const candidates = rankKnowledgeCandidates([...byRef.values()], scoringTerms);
+        if (candidates.length === 0) {
+            this.deliveryMode = degradedReason === undefined ? 'withheld' : 'degraded';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveryMode: this.deliveryMode,
+                ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+            };
+        }
+        // Metadata score-1 candidates are plausible enough to inspect but not
+        // relevant enough to inject. Fetch only the deterministic top K and
+        // re-score the original normalized terms against concise authored
+        // content (synthesis + step titles). Gets run concurrently inside the
+        // same host deadline as search; Promise.all preserves candidate order.
+        // Reuse successful fetched records below so escalation never causes a
+        // duplicate corpus/cache read. Any individual failure stays below the
+        // floor and records an honest degraded reason (fail open).
+        const fetchedRefs = [];
+        const prefetchedByRef = new Map();
+        const directCandidates = candidates.filter((candidate) => candidate.score >= RELEVANCE_FLOOR);
+        const nearMisses = candidates
+            .filter((candidate) => candidate.score < RELEVANCE_FLOOR)
+            .slice(0, MAX_CONTENT_RESCORE_CANDIDATES);
+        const nearMissResults = await Promise.all(nearMisses.map(({ hit }) => {
+            fetchedRefs.push(hit.ref);
+            return this.deps.corpus.get(hit.ref).catch((error) => degraded(`corpus get rejected for ${hit.ref}: ${errorReason(error)}`));
+        }));
+        const promotedCandidates = [];
+        for (let index = 0; index < nearMisses.length; index += 1) {
+            const candidate = nearMisses[index];
+            const result = nearMissResults[index];
+            prefetchedByRef.set(candidate.hit.ref, result);
+            if (result.status !== 'ok') {
+                if (degradedReason === undefined)
+                    degradedReason = result.reason;
+                continue;
+            }
+            const record = result.value;
+            if (record === null)
+                continue;
+            if (record.isSkillPayload === true)
+                continue;
+            if (record.retrievalVisible !== true)
+                continue;
+            const score = scoreKnowledgeRecord(candidate.hit, record, scoringTerms);
+            if (score >= RELEVANCE_FLOOR)
+                promotedCandidates.push({ hit: candidate.hit, score });
+        }
+        const ranked = rankScoredKnowledgeHits([
+            ...directCandidates,
+            ...promotedCandidates,
+        ]).map((candidate) => candidate.hit);
+        if (ranked.length === 0) {
+            this.fetchedRefs = fetchedRefs;
+            this.deliveryMode = degradedReason === undefined ? 'withheld' : 'degraded';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveryMode: this.deliveryMode,
+                ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+            };
+        }
+        // Fetch full content for ranked candidates and project packets, walking
+        // down the ranked list until MAX_SELECTED_PACKETS valid packets are
+        // found or candidates are exhausted (mono #1782). Three post-fetch
+        // guards can disqualify a candidate without spending its slot, promoting
+        // the next-ranked one: (1) content-level skill classification — excludes
+        // a legacy skill-shaped record (skill.md step attribute) or a
+        // jinn.skill.v1-backed record that slipped the wire kind filter, exactly
+        // as a wire kind:'skill' hit is excluded at selection time; (2)
+        // retrieval-visibility content verification (#1824, W2) — fail-closed
+        // where the other two are fail-open; (3) empty-packet honesty — a
+        // projection with zero excerpts and no synthesis is not evidence. A
+        // projection failure degrades that one ref to nothing-found rather than
+        // throwing into the caller (§3.5).
+        const packets = [];
+        for (const hit of ranked) {
+            if (packets.length >= MAX_SELECTED_PACKETS)
+                break;
+            let result = prefetchedByRef.get(hit.ref);
+            if (result === undefined) {
+                fetchedRefs.push(hit.ref);
+                result = await this.deps.corpus.get(hit.ref).catch((error) => degraded(`corpus get rejected for ${hit.ref}: ${errorReason(error)}`));
+            }
+            if (result.status !== 'ok') {
+                if (degradedReason === undefined)
+                    degradedReason = result.reason;
+                continue;
+            }
+            const record = result.value;
+            if (record === null)
+                continue;
+            if (record.isSkillPayload === true)
+                continue;
+            // Post-fetch content guard (#1824, W2): content is the truth, the
+            // search-hit's retrievalVisible was only a hint used to clear ranking.
+            // Fail-closed — undefined excludes, exactly like isSkillPayload's
+            // fail-open is the opposite case.
+            if (record.retrievalVisible !== true)
+                continue;
+            let packet;
+            try {
+                packet = projectKnowledgePacket(record);
+            }
+            catch (error) {
+                degradedReason ??= `packet projection failed for ${hit.ref}: ${errorReason(error)}`;
+                continue;
+            }
+            if (packet.excerpts.length === 0 && packet.synthesis === undefined)
+                continue;
+            packets.push(packet);
+        }
+        this.fetchedRefs = fetchedRefs;
+        this.providedRefs = packets.map((packet) => packet.ref);
+        this.eligibleRefs = [...this.providedRefs];
+        this.packets = packets;
+        if (packets.length === 0) {
+            this.deliveryMode = degradedReason === undefined ? 'withheld' : 'degraded';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: this.eligibleRefs,
+                deliveredRefs: [],
+                deliveryMode: this.deliveryMode,
+                ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+            };
+        }
+        const contextBlock = renderKnowledgePackets(packets);
+        this.deliveryMode = degradedReason === undefined ? 'delivered' : 'degraded';
+        this.deliveredContentHash = `sha256:${createHash('sha256').update(contextBlock).digest('hex')}`;
+        return {
+            contextBlock,
+            packets,
+            searchedTerms: terms,
+            retrievalFired: true,
+            eligibleRefs: this.eligibleRefs,
+            deliveredRefs: this.providedRefs,
+            deliveryMode: this.deliveryMode,
+            deliveredContentHash: this.deliveredContentHash,
+            ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+        };
+    }
+    noteUserTurn(content) {
+        this.pushTurn('user', content);
+    }
+    noteAssistantTurn(content) {
+        this.pushTurn('assistant', content);
+    }
+    pushTurn(role, content) {
+        // A turn is a zero-duration point event on the single unix-nano time base.
+        const nowNano = `${Date.now()}000000`;
+        this.trajectory.push({
+            spanId: randomUUID(),
+            parentSpanId: null,
+            kind: 'jinn.agent_turn',
+            name: 'turn',
+            startTimeUnixNano: nowNano,
+            endTimeUnixNano: nowNano,
+            attributes: { role, content },
+            redactedKeys: [],
+        });
+    }
+    noteToolCall(call) {
+        this.trajectory.push({ ...call, kind: 'jinn.tool_call', redactedKeys: call.redactedKeys ?? [] });
+    }
+    async end(outcome) {
+        const episode = EpisodeV1WriteSchema.parse({
+            schemaVersion: EPISODE_SCHEMA_VERSION,
+            episodeId: randomUUID(),
+            session: {
+                sessionId: this.meta.sessionId,
+                capturedAt: this.capturedAt,
+                kind: this.meta.kind ?? 'user',
+                ...(this.meta.parentSessionId ? { parentSessionId: this.meta.parentSessionId } : {}),
+            },
+            origin: {
+                writer: this.meta.harness.name,
+                build: this.meta.harness.version,
+            },
+            task: {
+                summary: this.meta.taskSummary,
+                distributionTags: this.meta.distributionTags ?? [],
+                ...(this.meta.repositorySlug ? { repositorySlug: this.meta.repositorySlug } : {}),
+            },
+            trajectory: this.trajectory,
+            environment: {
+                harness: this.meta.harness,
+                model: this.meta.model,
+                tools: this.meta.tools,
+                skillsLoadout: this.meta.skillsLoadout ?? [],
+            },
+            outcome: {
+                status: outcome.status,
+                verificationStrength: outcome.verifiabilityTier,
+                ...(outcome.summary !== undefined ? { summary: outcome.summary } : {}),
+                ...(outcome.acceptedDiff !== undefined ? { acceptedDiff: outcome.acceptedDiff } : {}),
+                ...(outcome.testRuns !== undefined ? { testRuns: outcome.testRuns } : {}),
+            },
+            cost: {
+                durationMs: outcome.durationMs,
+                ...(outcome.tokens ? { tokens: outcome.tokens } : {}),
+            },
+            retention: { policy: outcome.retentionPolicy },
+            provenance: 'contributed',
+        });
+        return completeSession(this.deps, {
+            contractVersion: JINN_PLUGIN_CONTRACT_VERSION,
+            episode,
+            activity: {
+                searchedTerms: this.searchedTerms,
+                providedRefs: this.providedRefs,
+                retrievalFired: this.retrievalFired,
+                eligibleRefs: this.eligibleRefs,
+                deliveredRefs: this.providedRefs,
+                deliveryMode: this.deliveryMode,
+                ...(this.deliveredContentHash
+                    ? { deliveredContentHash: this.deliveredContentHash }
+                    : {}),
+                surfacedRefs: [],
+                fetchedRefs: this.fetchedRefs,
+                installedSkillRefs: [],
+            },
+            eligibilityInputs: {
+                publicRepo: outcome.publicRepo,
+                acceptedDiff: outcome.acceptedDiff,
+            },
+        }, { providedPackets: this.packets });
+    }
+}
+/**
+ * Composes the block the host injects into the first user message, verbatim
+ * and cache-safe (rescope §3.4).
+ */
+function renderKnowledgePacket(packet) {
+    const lines = [
+        `${packet.task.summary} · ${packet.outcome.status}/${packet.outcome.verifiabilityTier}`,
+    ];
+    if (packet.synthesis)
+        lines.push(packet.synthesis);
+    for (const excerpt of packet.excerpts)
+        lines.push(`- ${excerpt.label}: ${excerpt.text}`);
+    const capturedDate = packet.attribution.capturedAt.slice(0, 10);
+    lines.push(`  source: ${packet.ref} · ${packet.attribution.origin} · captured ${capturedDate} · `
+        + `full episode: corpus_fetch ${packet.ref}`);
+    return lines.join('\n');
+}
+function renderKnowledgePackets(packets) {
+    return [
+        '[jinn corpus] Prior evidence relevant to this task:',
+        ...packets.map(renderKnowledgePacket),
+    ].join('\n');
+}
+export function createJinnPlugin(deps) {
+    return {
+        session(meta) {
+            return new PluginSession(deps, meta);
+        },
+        completeSession(input) {
+            return completeSession(deps, input);
+        },
+        history() {
+            return foldHistory(deps);
+        },
+        explain(sessionRef) {
+            return foldExplain(sessionRef, deps);
+        },
+        previewContribution(acknowledge = false) {
+            return previewContribution(deps, acknowledge);
+        },
+        async contributionLedger() {
+            try {
+                return await deps.contribution.ledger();
+            }
+            catch (error) {
+                return unavailable(`contribution ledger failed: ${errorReason(error)}`);
+            }
+        },
+        async disableContributionPublication() {
+            if (!deps.contribution.disableUnpublished) {
+                return unavailable('contribution disable is unavailable');
+            }
+            try {
+                return await deps.contribution.disableUnpublished();
+            }
+            catch (error) {
+                return unavailable(`contribution disable failed: ${errorReason(error)}`);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+import type { PortResult } from '../outcome.js';
+import type { ContributionCandidateV1 } from '../schemas/contribution-candidate.js';
+export type ContributionLocalState = 'recorded' | 'minted' | 'rejected';
+export type ContributionPublicationState = 'disabled' | 'preview-required' | 'queued' | 'published' | 'vetoed';
+export type ContributionStatus = ContributionLocalState | Exclude<ContributionPublicationState, 'disabled'>;
+export interface ContributionState {
+    localState: ContributionLocalState;
+    publicationState: ContributionPublicationState;
+    mintRef?: string;
+    publicationRef?: string;
+}
+export interface ContributionStatusSnapshot extends ContributionState {
+    status: ContributionStatus;
+}
+export interface ContributionLedgerEntry extends ContributionStatusSnapshot {
+    recordId: string;
+    sourceId: string;
+    /** Absent when a migrated reference no longer resolves to retained evidence. */
+    createdAt?: string;
+    verifiabilityTier?: 'user-accepted' | 'tests-passed';
+    /** Sanitized repository facts used by the local first-share preview. */
+    repositorySlug?: string;
+    baseCommit?: string;
+}
+export interface ContributionRecordOptions {
+    /** Persist a durable veto in the same atomic write that creates the record. */
+    publicationState?: 'vetoed';
+}
+/** Collapse the independent local and outbound axes into one display status. */
+export declare function deriveContributionStatus(state: Pick<ContributionState, 'localState' | 'publicationState'>): ContributionStatus;
+export interface ContributionPort {
+    /** Production verifies the canonical Episode, then stores only its reference and state. */
+    recordMineable(candidate: ContributionCandidateV1, options?: ContributionRecordOptions): Promise<PortResult<{
+        recordId: string;
+    }>>;
+    ledger(): Promise<PortResult<ContributionLedgerEntry[]>>;
+    /** Retained name for adapter compatibility; reports both axes and the derived status. */
+    mintStatus(recordId: string): Promise<PortResult<ContributionStatusSnapshot>>;
+    authorize(recordId: string): Promise<PortResult<{
+        recordId: string;
+        publicationState: 'queued';
+        status: 'queued';
+    }>>;
+    veto(recordId: string): Promise<PortResult<{
+        recordId: string;
+        publicationState: 'vetoed';
+        status: 'vetoed';
+    }>>;
+    /** Disable every unpublished standing authorization when sharing is turned off. */
+    disableUnpublished?(): Promise<PortResult<{
+        recordIds: string[];
+    }>>;
+}

package/dist/ports/contribution-port.js

@@ -0,0 +1,14 @@
+/** Collapse the independent local and outbound axes into one display status. */
+export function deriveContributionStatus(state) {
+    if (state.publicationState === 'published')
+        return 'published';
+    if (state.publicationState === 'vetoed')
+        return 'vetoed';
+    if (state.localState === 'rejected')
+        return 'rejected';
+    if (state.publicationState === 'preview-required')
+        return 'preview-required';
+    if (state.publicationState === 'queued')
+        return 'queued';
+    return state.localState;
+}