@jinn-network/plugin 0.1.0-canary.3afae198

package/dist/eligibility.d.ts

@@ -0,0 +1,12 @@
+/** Cheap eligibility candidate-verdict (architecture §5). Pure over the
+ *  SessionOutcome facts the core already holds. Authoritative validation
+ *  (Docker F2P/P2P, resolvable repo@commit) stays sidecar-side. */
+import type { EligibilityVerdict } from './schemas/eligibility-verdict.js';
+export interface EligibilityInputs {
+    status: 'completed' | 'failed' | 'abandoned';
+    verifiabilityTier: 'user-accepted' | 'tests-passed' | 'evaluator-verified';
+    retentionPolicy: 'local-private' | 'contribution-eligible';
+    publicRepo?: boolean;
+    acceptedDiff?: boolean;
+}
+export declare function deriveEligibility(input: EligibilityInputs, checkedAt: string): EligibilityVerdict;

package/dist/eligibility.js

@@ -0,0 +1,12 @@
+export function deriveEligibility(input, checkedAt) {
+    if (input.status !== 'completed') {
+        return { eligible: false, reason: 'outcome not completed', checkedAt };
+    }
+    if (input.retentionPolicy !== 'contribution-eligible') {
+        return { eligible: false, reason: 'retention is local-private', checkedAt };
+    }
+    if (!input.acceptedDiff && !input.publicRepo) {
+        return { eligible: false, reason: 'no accepted diff signal', checkedAt };
+    }
+    return { eligible: true, reason: 'completed with accepted-diff/public-repo signal', checkedAt };
+}

package/dist/history.d.ts

@@ -0,0 +1,35 @@
+/** Derived history + explain views (product design §4.5). Owns no facts —
+ *  recomputed from Evidence + Contribution + LocalLearning on every call, so
+ *  deleting any cache leaves output identical (there is no cache). */
+import { type ContributionPort } from './ports/contribution-port.js';
+import type { EvidencePort } from './ports/evidence-port.js';
+import type { LocalLearningPort } from './ports/local-learning-port.js';
+import type { EligibilityVerdict } from './schemas/eligibility-verdict.js';
+import type { HistoryEntry } from './schemas/history-entry.js';
+export interface HistoryDeps {
+    evidence: EvidencePort;
+    contribution: ContributionPort;
+    localLearning: LocalLearningPort;
+}
+export interface HistoryResult {
+    entries: HistoryEntry[];
+    degraded: boolean;
+    unavailable: boolean;
+    reason?: string;
+}
+export interface SessionExplanation {
+    sessionRef: string;
+    found: boolean;
+    searchedTerms: string[];
+    providedRefs: string[];
+    captureStatus: 'captured' | 'not-captured';
+    eligibility: EligibilityVerdict | null;
+    contributionState: {
+        status: HistoryEntry['contributionState']['status'];
+        anchorRef?: string;
+    };
+    degraded: boolean;
+    reason?: string;
+}
+export declare function foldHistory(deps: HistoryDeps): Promise<HistoryResult>;
+export declare function foldExplain(sessionRef: string, deps: HistoryDeps): Promise<SessionExplanation>;

package/dist/history.js

@@ -0,0 +1,140 @@
+/** Derived history + explain views (product design §4.5). Owns no facts —
+ *  recomputed from Evidence + Contribution + LocalLearning on every call, so
+ *  deleting any cache leaves output identical (there is no cache). */
+import { deriveContributionStatus, } from './ports/contribution-port.js';
+import { unwrap } from './outcome.js';
+/** Fail-open list unwrap that records a labelled reason on non-ok reads. */
+function collect(res, label, fallback, reasons) {
+    const { value, reason } = unwrap(res, fallback);
+    if (reason !== undefined)
+        reasons.push(`${label}: ${reason}`);
+    return value;
+}
+function ledgerByEpisode(ledger) {
+    const map = new Map();
+    for (const row of ledger)
+        map.set(row.sourceId, row);
+    return map;
+}
+function contributionState(row, available = true) {
+    if (!available)
+        return { status: 'unavailable' };
+    if (!row)
+        return { status: 'none' };
+    const anchorRef = row.publicationRef ?? row.mintRef;
+    return {
+        status: deriveContributionStatus(row),
+        ...(anchorRef !== undefined ? { anchorRef } : {}),
+    };
+}
+/**
+ * New episodes persist the authoritative completion verdict. Historical v1
+ * records omit it, so reads stay backward compatible and honestly indeterminate
+ * rather than silently manufacturing a verdict from incomplete inputs.
+ */
+function episodeEligibility(ep) {
+    return ep.eligibility ?? null;
+}
+/**
+ * Canonical searched/provided activity from the new fields, falling back to
+ * the legacy surfaced/fetched refs for episodes captured before the rescope
+ * (rescope §3.6). An episode is "legacy" here when both new fields are empty
+ * AND at least one legacy field is not — a genuinely new episode with a
+ * nothing-found result has both sides empty, so the fallback is a no-op for it.
+ * Reads defensively (`?? []`): an `EvidencePort` is not required to
+ * schema-validate on read (the in-memory test double does not), so a record
+ * older than any given field must not crash the fold.
+ */
+function canonicalKnowledgeActivity(activity) {
+    if (!activity)
+        return { searchedTerms: [], providedRefs: [] };
+    const searchedTerms = activity.searchedTerms ?? [];
+    const providedRefs = activity.providedRefs ?? [];
+    const surfacedRefs = activity.surfacedRefs ?? [];
+    const fetchedRefs = activity.fetchedRefs ?? [];
+    const installedSkillRefs = activity.installedSkillRefs ?? [];
+    const isLegacy = searchedTerms.length === 0
+        && providedRefs.length === 0
+        && (surfacedRefs.length > 0 || fetchedRefs.length > 0 || installedSkillRefs.length > 0);
+    return isLegacy
+        ? { searchedTerms: surfacedRefs, providedRefs: fetchedRefs }
+        : { searchedTerms, providedRefs };
+}
+function knowledgeCounts(activity) {
+    const canonical = canonicalKnowledgeActivity(activity);
+    return { surfaced: canonical.searchedTerms.length, used: canonical.providedRefs.length };
+}
+function skillsBySession(skills) {
+    const bySession = new Map();
+    for (const skill of skills) {
+        for (const sessionId of skill.sourceSessionIds) {
+            const rows = bySession.get(sessionId) ?? [];
+            if (!rows.some((row) => row.ref === skill.ref && row.state === skill.state)) {
+                rows.push({ ref: skill.ref, state: skill.state });
+            }
+            bySession.set(sessionId, rows);
+        }
+    }
+    return bySession;
+}
+export async function foldHistory(deps) {
+    const reasons = [];
+    const episodesResult = await deps.evidence.list();
+    const episodes = collect(episodesResult, 'evidence', [], reasons);
+    const ledgerResult = await deps.contribution.ledger();
+    const ledger = collect(ledgerResult, 'contribution', [], reasons);
+    const skillsResult = deps.localLearning.skills
+        ? await deps.localLearning.skills()
+        : { status: 'unavailable', reason: 'skill provenance is unavailable' };
+    const skills = collect(skillsResult, 'localLearning', [], reasons);
+    const byEpisode = ledgerByEpisode(ledger);
+    const bySession = skillsBySession(skills);
+    const contributionAvailable = ledgerResult.status !== 'unavailable';
+    const skillsAvailable = skillsResult.status !== 'unavailable';
+    const entries = [...episodes]
+        .filter((ep) => ep.session.kind !== 'host-internal')
+        .sort((a, b) => b.session.capturedAt.localeCompare(a.session.capturedAt))
+        .map((ep) => {
+        const counts = knowledgeCounts(ep.activity);
+        return {
+            sessionId: ep.session.sessionId,
+            capturedAt: ep.session.capturedAt,
+            taskSummary: ep.task.summary,
+            knowledgeSurfaced: ep.activity ? counts.surfaced : null,
+            knowledgeUsed: ep.activity ? counts.used : null,
+            captureStatus: 'captured',
+            eligibility: episodeEligibility(ep),
+            contributionState: contributionState(byEpisode.get(ep.episodeId), contributionAvailable),
+            distilledSkills: skillsAvailable ? bySession.get(ep.session.sessionId) ?? [] : null,
+        };
+    });
+    const legacyFactsUnavailable = episodes.some((ep) => !ep.activity || !ep.eligibility);
+    if (legacyFactsUnavailable)
+        reasons.push('one or more episodes predate activity or eligibility facts');
+    const evidenceUnavailable = episodesResult.status === 'unavailable';
+    return reasons.length > 0
+        ? { entries, degraded: true, unavailable: evidenceUnavailable, reason: reasons.join('; ') }
+        : { entries, degraded: false, unavailable: false };
+}
+export async function foldExplain(sessionRef, deps) {
+    const reasons = [];
+    const episodes = collect(await deps.evidence.list(), 'evidence', [], reasons);
+    const ledgerResult = await deps.contribution.ledger();
+    const ledger = collect(ledgerResult, 'contribution', [], reasons);
+    const episode = episodes.find((ep) => ep.session.sessionId === sessionRef);
+    const contribution = episode
+        ? contributionState(ledger.find((row) => row.sourceId === episode.episodeId), ledgerResult.status !== 'unavailable')
+        : contributionState(undefined, ledgerResult.status !== 'unavailable');
+    const activity = canonicalKnowledgeActivity(episode?.activity);
+    return {
+        sessionRef,
+        found: Boolean(episode),
+        searchedTerms: activity.searchedTerms,
+        providedRefs: activity.providedRefs,
+        captureStatus: episode ? 'captured' : 'not-captured',
+        eligibility: episode ? episodeEligibility(episode) : null,
+        contributionState: contribution,
+        degraded: reasons.length > 0,
+        ...(reasons.length > 0 ? { reason: reasons.join('; ') } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export type { PortResult } from './outcome.js';
+export { ok, degraded, unavailable, valueOr, unwrap } from './outcome.js';
+export { EPISODE_SCHEMA_VERSION, EpisodeV1Schema, EpisodeV1WriteSchema, SessionActivityFactsSchema, SessionActivityFactsWriteSchema, VERIFICATION_STRENGTHS, VerificationStrengthSchema, } from './schemas/episode.js';
+export type { EpisodeV1, EpisodeV1Write, SessionActivityFacts, VerificationStrength, } from './schemas/episode.js';
+export { CONTRIBUTION_CANDIDATE_SCHEMA_VERSION, ContributionCandidateV1ProjectionSchema, ContributionCandidateV1Schema, } from './schemas/contribution-candidate.js';
+export type { ContributionCandidateV1 } from './schemas/contribution-candidate.js';
+export { KnowledgeHitSchema } from './schemas/knowledge-hit.js';
+export type { KnowledgeHit } from './schemas/knowledge-hit.js';
+export { EligibilityVerdictSchema } from './schemas/eligibility-verdict.js';
+export type { EligibilityVerdict } from './schemas/eligibility-verdict.js';
+export { SessionSummarySchema } from './schemas/session-summary.js';
+export type { SessionSummary } from './schemas/session-summary.js';
+export { HistoryEntrySchema } from './schemas/history-entry.js';
+export type { HistoryEntry } from './schemas/history-entry.js';
+export type { CorpusPort, CorpusRecord, CorpusRecordStep } from './ports/corpus-port.js';
+export type { EvidencePort, EvidenceListQuery, EvidenceRetentionPolicy } from './ports/evidence-port.js';
+export { deriveContributionStatus } from './ports/contribution-port.js';
+export type { ContributionPort, ContributionLedgerEntry, ContributionLocalState, ContributionPublicationState, ContributionState, ContributionStatus, ContributionStatusSnapshot, } from './ports/contribution-port.js';
+export type { LocalLearningPort, LocalLearningRun, LocalLearningSkill, } from './ports/local-learning-port.js';
+export type { SkillsPort, SkillRecord } from './ports/skills-port.js';
+export { createJinnPlugin, JINN_PLUGIN_CONTRACT_VERSION, PluginSession } from './plugin.js';
+export type { CompleteSessionEligibilityInputs, CompleteSessionInput, JinnPlugin, JinnPluginDeps, SessionMeta, FirstTurnPickupResult, ToolCallEvent, SessionOutcome, SessionEndResult, ContributionCompletionReceipt, ContributionPreview, } from './plugin.js';
+export { PickupConfigSchema, DEFAULT_PICKUP_CONFIG, parsePickupConfig, TIER_ORDER } from './schemas/pickup-config.js';
+export type { PickupConfig, Tier } from './schemas/pickup-config.js';
+export { deriveRepositorySearchTerms, discriminatingTerms, deriveSearchTerms, classifyPayload, dedupeKnowledgeHits, scoreKnowledgeHit, selectKnowledgeHits, rankKnowledgeHits, MAX_SELECTED_PACKETS, } from './pickup.js';
+export { KNOWLEDGE_PACKET_SCHEMA_VERSION, KnowledgePacketSchema, KnowledgePacketExcerptSchema, DEFAULT_PACKET_CHAR_BUDGET, projectKnowledgePacket, truncateLineBoundary, } from './schemas/knowledge-packet.js';
+export type { KnowledgePacket, KnowledgePacketExcerpt, KnowledgePacketBudget, } from './schemas/knowledge-packet.js';
+export { RETRIEVAL_VISIBLE_TAG, hasRetrievalMark } from './visibility.js';
+export { deriveEligibility } from './eligibility.js';
+export type { EligibilityInputs } from './eligibility.js';
+export { foldHistory, foldExplain } from './history.js';
+export type { HistoryResult, SessionExplanation, HistoryDeps } from './history.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+export { ok, degraded, unavailable, valueOr, unwrap } from './outcome.js';
+export { EPISODE_SCHEMA_VERSION, EpisodeV1Schema, EpisodeV1WriteSchema, SessionActivityFactsSchema, SessionActivityFactsWriteSchema, VERIFICATION_STRENGTHS, VerificationStrengthSchema, } from './schemas/episode.js';
+export { CONTRIBUTION_CANDIDATE_SCHEMA_VERSION, ContributionCandidateV1ProjectionSchema, ContributionCandidateV1Schema, } from './schemas/contribution-candidate.js';
+export { KnowledgeHitSchema } from './schemas/knowledge-hit.js';
+export { EligibilityVerdictSchema } from './schemas/eligibility-verdict.js';
+export { SessionSummarySchema } from './schemas/session-summary.js';
+export { HistoryEntrySchema } from './schemas/history-entry.js';
+export { deriveContributionStatus } from './ports/contribution-port.js';
+export { createJinnPlugin, JINN_PLUGIN_CONTRACT_VERSION, PluginSession } from './plugin.js';
+export { PickupConfigSchema, DEFAULT_PICKUP_CONFIG, parsePickupConfig, TIER_ORDER } from './schemas/pickup-config.js';
+export { deriveRepositorySearchTerms, discriminatingTerms, deriveSearchTerms, classifyPayload, dedupeKnowledgeHits, scoreKnowledgeHit, selectKnowledgeHits, rankKnowledgeHits, MAX_SELECTED_PACKETS, } from './pickup.js';
+export { KNOWLEDGE_PACKET_SCHEMA_VERSION, KnowledgePacketSchema, KnowledgePacketExcerptSchema, DEFAULT_PACKET_CHAR_BUDGET, projectKnowledgePacket, truncateLineBoundary, } from './schemas/knowledge-packet.js';
+export { RETRIEVAL_VISIBLE_TAG, hasRetrievalMark } from './visibility.js';
+export { deriveEligibility } from './eligibility.js';
+export { foldHistory, foldExplain } from './history.js';

package/dist/outcome.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Port result envelope (architecture spec §4). Adapters may throw; ports
+ * never do — every port method resolves a PortResult so a failure surfaces
+ * as a typed outcome, never a crash into the host session.
+ */
+export type PortResult<T> = {
+    status: 'ok';
+    value: T;
+} | {
+    status: 'degraded';
+    reason: string;
+    value?: T;
+} | {
+    status: 'unavailable';
+    reason: string;
+};
+export declare function ok<T>(value: T): PortResult<T>;
+export declare function degraded<T>(reason: string, value?: T): PortResult<T>;
+export declare function unavailable<T = never>(reason: string): PortResult<T>;
+/** Fail-open value access: ok → value; degraded → value ?? fallback; unavailable → fallback. */
+export declare function valueOr<T>(res: PortResult<T>, fallback: T): T;
+/** Like valueOr, but also surfaces the failure reason so callers can collect it. */
+export declare function unwrap<T>(res: PortResult<T>, fallback: T): {
+    value: T;
+    reason?: string;
+};

package/dist/outcome.js

@@ -0,0 +1,23 @@
+export function ok(value) {
+    return { status: 'ok', value };
+}
+export function degraded(reason, value) {
+    return { status: 'degraded', reason, value };
+}
+export function unavailable(reason) {
+    return { status: 'unavailable', reason };
+}
+/** Fail-open value access: ok → value; degraded → value ?? fallback; unavailable → fallback. */
+export function valueOr(res, fallback) {
+    if (res.status === 'ok')
+        return res.value;
+    if (res.status === 'degraded')
+        return res.value ?? fallback;
+    return fallback;
+}
+/** Like valueOr, but also surfaces the failure reason so callers can collect it. */
+export function unwrap(res, fallback) {
+    if (res.status === 'ok')
+        return { value: res.value };
+    return { value: res.status === 'degraded' ? res.value ?? fallback : fallback, reason: res.reason };
+}

package/dist/pickup.d.ts

@@ -0,0 +1,101 @@
+/** Evidence-first pickup policy (rescope design §3.3; lexical v2 term
+ *  selection — #1791, #1790, #1789). No I/O: term derivation + selection
+ *  only. Orchestration (search/get over ports, packet projection, rendering)
+ *  lives in plugin.ts. */
+import type { CorpusRecord } from './ports/corpus-port.js';
+import type { KnowledgeHit } from './schemas/knowledge-hit.js';
+export declare const STOPWORDS: ReadonlySet<string>;
+/**
+ * The repository vocabulary shared by interactive pickup and repo-scoped
+ * corpus probes. A full `owner/repo` slug does not occur in record text; the
+ * repository name is the searchable term (#1790). Keep the minimum length in
+ * this one helper so non-session consumers cannot drift from pickup.
+ */
+export declare function deriveRepositorySearchTerms(repositorySlug?: string): string[];
+/**
+ * Up to `maxTerms` deterministic lowercase search terms, in priority order
+ * (rescope §3.3, lexical v2 — #1791/#1790/#1789): backticked/quoted tokens
+ * (edge-stripped, near-verbatim); identifier-shaped tokens — a `/`-bearing
+ * one also contributes its path segments, right after the full token; the
+ * session repository's NAME (not its full slug, #1790); the remaining
+ * non-stopword tokens (>=4 chars) in MESSAGE ORDER — order of first
+ * appearance, not longest-first (#1791: length is not a retrievability
+ * signal against a corpus of short summaries and tags). Operates over the
+ * whole message (not just the first line). Deduplicated.
+ */
+export declare function deriveSearchTerms(message: string, repositorySlug?: string, maxTerms?: number): string[];
+/** Ports classify_payload — 'skill' or 'unknown'. Prefers the explicit
+ *  payloadKind classification field; falls back to hit.kind === 'skill'. */
+export declare function classifyPayload(hit: Pick<KnowledgeHit, 'payloadKind' | 'kind'>): 'skill' | 'unknown';
+/** Dedup by ref, then by content key (rescope §3.3 step 2). */
+export declare function dedupeKnowledgeHits(hits: KnowledgeHit[]): KnowledgeHit[];
+export declare const RELEVANCE_FLOOR = 2;
+export declare const MAX_SELECTED_PACKETS = 2;
+export declare const MAX_CONTENT_RESCORE_CANDIDATES = 3;
+export interface ScoredKnowledgeHit {
+    hit: KnowledgeHit;
+    score: number;
+}
+/**
+ * The scoring vocabulary: `terms` minus the repository-name term (#1886).
+ *
+ * The repository name tags every record in an in-repo corpus, so it matches
+ * everything and discriminates nothing — yet it counted 1 toward
+ * `RELEVANCE_FLOOR`, halving the effective floor for any query issued inside
+ * the repository. It remains a *search* term (it is what surfaces
+ * repo-relevant records at all); it just no longer helps a record clear the
+ * floor. Callers pass the full list to search and this list to scoring.
+ */
+export declare function discriminatingTerms(terms: string[], repositorySlug?: string): string[];
+/** Count of matched terms across `taskSummary + tags` (rescope §3.3 step 3,
+ *  lexical v2 — #1790/#1791) — every match counts 1. The repository-slug
+ *  match used to count 2, but the slug it matched against could never
+ *  appear in a record's text (#1790); the repository's NAME is now a
+ *  normal derived term (see `deriveSearchTerms` step 3) and scores like any
+ *  other term, with no special case. */
+export declare function scoreKnowledgeHit(hit: KnowledgeHit, terms: string[]): number;
+/**
+ * Re-score an already plausible metadata candidate against the two concise,
+ * human-authored content fields available after `CorpusPort.get`: synthesis
+ * and step titles. Each original normalized term contributes at most one
+ * point across metadata + content, so repeating the same match in synthesis
+ * cannot manufacture relevance.
+ */
+export declare function scoreKnowledgeRecord(hit: KnowledgeHit, record: CorpusRecord, terms: string[]): number;
+/** Return a copied, deterministically ranked scored-candidate list. */
+export declare function rankScoredKnowledgeHits(candidates: ScoredKnowledgeHit[]): ScoredKnowledgeHit[];
+/**
+ * Eligible, deduplicated candidates that have at least one metadata match.
+ * Score-1 results are intentionally retained here for the bounded content
+ * escalation; `rankKnowledgeHits` remains the honest floor-enforcing API.
+ */
+export declare function rankKnowledgeCandidates(hits: KnowledgeHit[], terms: string[]): ScoredKnowledgeHit[];
+/**
+ * Full ranked candidate pool (rescope §3.3 selection policy): drop skill
+ * hits, dedup, score, apply the relevance floor (honest nothing-found below
+ * it), rank score desc → tier desc → recency desc — every candidate that
+ * clears the floor, not sliced to `MAX_SELECTED_PACKETS`.
+ *
+ * Content-level guards that can only run after a candidate's content is
+ * fetched (mono #1782: post-fetch skill-payload classification, empty-packet
+ * honesty) need to walk past a disqualified top candidate to the
+ * next-ranked one, so the orchestrator (`plugin.ts` `firstTurnPickup`) walks
+ * this unsliced list and does its own promotion-aware slicing.
+ * `selectKnowledgeHits` remains the pre-guards convenience wrapper for
+ * callers that only need the top slice.
+ *
+ * Also fail-closed allowlist-filters to `retrievalVisible === true` (#1824,
+ * W2) — absence of the field excludes the hit; this is the ranking-side half
+ * of the two-layer enforcement, `firstTurnPickup`'s post-fetch content guard
+ * is the other half.
+ */
+export declare function rankKnowledgeHits(hits: KnowledgeHit[], terms: string[]): KnowledgeHit[];
+/**
+ * Evidence-first selection (rescope §3.3): the top `MAX_SELECTED_PACKETS` of
+ * `rankKnowledgeHits`. A caller that also needs to apply the post-fetch
+ * content-level guards (mono #1782) should walk `rankKnowledgeHits` directly
+ * instead — slicing here happens before those guards can run, so a
+ * candidate they disqualify would lose its slot rather than promoting the
+ * next-ranked one.
+ */
+export declare function selectKnowledgeHits(hits: KnowledgeHit[], terms: string[]): KnowledgeHit[];