@jinn-network/client 0.1.9 → 0.2.0

package/node_modules/@jinn-network/plugin/dist/schemas/knowledge-packet.js

@@ -0,0 +1,213 @@
+/**
+ * `jinn.knowledge-packet.v1` — the unit of evidence supplied to the agent
+ * (rescope design §3.2). A versioned, pure, deterministic projection of a
+ * `CorpusRecord`: presentation-only, re-derivable at any time, never stored
+ * as new truth.
+ */
+import { z } from 'zod';
+import { TIER_ORDER } from './pickup-config.js';
+export const KNOWLEDGE_PACKET_SCHEMA_VERSION = 'jinn.knowledge-packet.v1';
+export const KnowledgePacketExcerptSchema = z.strictObject({
+    label: z.enum(['failure', 'fix', 'command', 'diff', 'note']),
+    text: z.string().min(1),
+});
+export const KnowledgePacketSchema = z.strictObject({
+    schemaVersion: z.literal(KNOWLEDGE_PACKET_SCHEMA_VERSION),
+    ref: z.string().min(1),
+    task: z.strictObject({
+        summary: z.string().min(1),
+        repositorySlug: z.string().min(1).optional(),
+    }),
+    outcome: z.strictObject({
+        status: z.enum(['completed', 'failed', 'abandoned']),
+        verifiabilityTier: z.enum(TIER_ORDER),
+    }),
+    /** The record's own synthesis, when the record carries one. Never generated here. */
+    synthesis: z.string().min(1).optional(),
+    excerpts: z.array(KnowledgePacketExcerptSchema),
+    attribution: z.strictObject({
+        provenance: z.enum(['imported', 'contributed', 'derived-from-history']),
+        capturedAt: z.iso.datetime(),
+        origin: z.string().min(1),
+    }),
+});
+export const DEFAULT_PACKET_CHAR_BUDGET = 3_500;
+/**
+ * Read a well-known string-shaped step attribute. Steps follow the existing
+ * capture convention seen throughout this codebase's episode/trace fixtures:
+ * `tool.args` (command invoked) / `tool.result` (output) / `tool.exitCode`
+ * (numeric exit status) / `diff` (a unified-diff excerpt) / `note` or
+ * `turn.text` (free-form remark, mirroring the episode `jinn.agent_turn`
+ * attribute convention).
+ */
+function attrString(attributes, key) {
+    const value = attributes[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function stepCommand(step) {
+    return attrString(step.attributes, 'tool.args') ?? attrString(step.attributes, 'command');
+}
+function stepOutput(step) {
+    return attrString(step.attributes, 'tool.result') ?? attrString(step.attributes, 'result');
+}
+function stepExitCode(step) {
+    const value = step.attributes['tool.exitCode'] ?? step.attributes['exitCode'];
+    return typeof value === 'number' ? value : undefined;
+}
+function stepDiff(step) {
+    return attrString(step.attributes, 'diff');
+}
+function stepNote(step) {
+    return attrString(step.attributes, 'note') ?? attrString(step.attributes, 'turn.text');
+}
+const EXCERPT_LABELS = new Set([
+    'failure', 'fix', 'command', 'diff', 'note',
+]);
+/**
+ * Seed-authored evidence (`packages/layer/src/seed-import/
+ * episode-execute.ts`) carries its own excerpt directly on the step —
+ * `seed.step.label` (one of this schema's five excerpt labels) and
+ * `seed.step.text` (the excerpt content, already selected by the seed
+ * author offline) — rather than the `tool.args`/`tool.exitCode` real-capture
+ * convention `stepCommand`/`stepExitCode` read. Trust it verbatim: the
+ * heuristic below exists to *infer* an excerpt from a raw trajectory; a seed
+ * step has already done that inference by hand, so re-deriving it from a
+ * synthetic exit code would only risk corrupting what the seed author wrote.
+ */
+function seedStepExcerpt(step) {
+    const label = step.attributes['seed.step.label'];
+    const text = attrString(step.attributes, 'seed.step.text');
+    if (typeof label !== 'string' || text === undefined)
+        return undefined;
+    return EXCERPT_LABELS.has(label)
+        ? { label: label, text }
+        : undefined;
+}
+/**
+ * Deterministic excerpt selection over a record's steps, in step order.
+ * Seed-authored steps (see `seedStepExcerpt`) are trusted verbatim, in step
+ * order, when present. Otherwise: the first failing command with its
+ * output, the next command after it that is not itself a failure (the
+ * correction), the last passing command overall (the final backstop), and a
+ * diff step when present. Falls back to a single free-form note when
+ * nothing command-shaped is found. Selects only — never paraphrases.
+ */
+function selectExcerpts(steps) {
+    const seedExcerpts = steps
+        .map(seedStepExcerpt)
+        .filter((candidate) => candidate !== undefined);
+    if (seedExcerpts.length > 0)
+        return seedExcerpts;
+    const excerpts = [];
+    let failureIndex = -1;
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const command = stepCommand(step);
+        const exitCode = stepExitCode(step);
+        if (command !== undefined && exitCode !== undefined && exitCode !== 0) {
+            const output = stepOutput(step);
+            excerpts.push({ label: 'failure', text: output ? `${command}\n${output}` : command });
+            failureIndex = i;
+            break;
+        }
+    }
+    if (failureIndex >= 0) {
+        for (let i = failureIndex + 1; i < steps.length; i++) {
+            const step = steps[i];
+            const command = stepCommand(step);
+            const exitCode = stepExitCode(step);
+            if (command !== undefined && exitCode !== undefined && exitCode === 0) {
+                excerpts.push({ label: 'fix', text: command });
+                break;
+            }
+        }
+    }
+    let lastPassing;
+    for (const step of steps) {
+        const command = stepCommand(step);
+        const exitCode = stepExitCode(step);
+        if (command !== undefined && exitCode === 0)
+            lastPassing = command;
+    }
+    if (lastPassing !== undefined)
+        excerpts.push({ label: 'command', text: lastPassing });
+    const diffStep = steps.find((step) => stepDiff(step) !== undefined);
+    if (diffStep !== undefined)
+        excerpts.push({ label: 'diff', text: stepDiff(diffStep) });
+    if (excerpts.length === 0) {
+        const noteStep = steps.find((step) => stepNote(step) !== undefined);
+        if (noteStep !== undefined)
+            excerpts.push({ label: 'note', text: stepNote(noteStep) });
+    }
+    return excerpts;
+}
+/**
+ * Line-boundary-aware truncation ending with an explicit, pointer-bearing
+ * tail. Returns an empty string when the budget cannot fit both meaningful
+ * source text and the complete tail.
+ */
+export function truncateLineBoundary(text, maxChars, ref) {
+    if (text.length <= maxChars)
+        return text;
+    const tail = `\n[truncated — full episode: corpus_fetch ${ref}]`;
+    const budget = maxChars - tail.length;
+    if (budget <= 0)
+        return '';
+    let cut = text.slice(0, budget);
+    const lastNewline = cut.lastIndexOf('\n');
+    if (lastNewline > 0)
+        cut = cut.slice(0, lastNewline);
+    if (cut.trim().length === 0)
+        return '';
+    return `${cut}${tail}`;
+}
+/**
+ * Pure deterministic projection of a `CorpusRecord` into a `KnowledgePacket`
+ * (rescope §3.2). Selects and truncates; never paraphrases. Enforces the
+ * combined synthesis+excerpts char budget (default 3,500 — two packets at the
+ * default budget total 7,000, satisfying §3.5's combined ceiling).
+ */
+export function projectKnowledgePacket(record, budget = {}) {
+    const maxChars = budget.maxChars ?? DEFAULT_PACKET_CHAR_BUDGET;
+    let synthesis = record.synthesis;
+    if (synthesis !== undefined && synthesis.length > maxChars) {
+        synthesis = truncateLineBoundary(synthesis, maxChars, record.ref);
+    }
+    const candidates = selectExcerpts(record.steps);
+    const excerpts = [];
+    let used = synthesis?.length ?? 0;
+    for (const candidate of candidates) {
+        const remaining = maxChars - used;
+        if (remaining <= 0)
+            break;
+        if (candidate.text.length <= remaining) {
+            excerpts.push(candidate);
+            used += candidate.text.length;
+        }
+        else {
+            const text = truncateLineBoundary(candidate.text, remaining, record.ref);
+            if (text.length > 0)
+                excerpts.push({ label: candidate.label, text });
+            break;
+        }
+    }
+    return KnowledgePacketSchema.parse({
+        schemaVersion: KNOWLEDGE_PACKET_SCHEMA_VERSION,
+        ref: record.ref,
+        task: {
+            summary: record.task.summary,
+            ...(record.task.repositorySlug ? { repositorySlug: record.task.repositorySlug } : {}),
+        },
+        outcome: {
+            status: record.outcome.status,
+            verifiabilityTier: record.outcome.verifiabilityTier,
+        },
+        ...(synthesis ? { synthesis } : {}),
+        excerpts,
+        attribution: {
+            provenance: record.provenance,
+            capturedAt: record.capturedAt,
+            origin: record.origin,
+        },
+    });
+}

package/node_modules/@jinn-network/plugin/dist/schemas/pickup-config.d.ts

@@ -0,0 +1,20 @@
+/** Pickup policy config — ported from pickup.py DEFAULT_CONFIG. Injected as a
+ *  typed object; no pickup.json fs read in core (architecture §6). */
+import { z } from 'zod';
+export declare const TIER_ORDER: readonly ["user-accepted", "tests-passed", "evaluator-verified"];
+export type Tier = (typeof TIER_ORDER)[number];
+export declare const PickupConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    autoAdopt: z.ZodDefault<z.ZodBoolean>;
+    autoAdoptTier: z.ZodDefault<z.ZodEnum<{
+        "user-accepted": "user-accepted";
+        "tests-passed": "tests-passed";
+        "evaluator-verified": "evaluator-verified";
+    }>>;
+    maxCandidates: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type PickupConfig = z.infer<typeof PickupConfigSchema>;
+export declare const DEFAULT_PICKUP_CONFIG: PickupConfig;
+/** Merge partial input over defaults; a bad autoAdoptTier coerces to default
+ *  (mirrors load_config()'s TIER_ORDER guard). Never throws — bad input → defaults. */
+export declare function parsePickupConfig(input?: unknown): PickupConfig;

package/node_modules/@jinn-network/plugin/dist/schemas/pickup-config.js

@@ -0,0 +1,34 @@
+/** Pickup policy config — ported from pickup.py DEFAULT_CONFIG. Injected as a
+ *  typed object; no pickup.json fs read in core (architecture §6). */
+import { z } from 'zod';
+// Weakest → strongest; mirrors VERIFIABILITY_TIERS in the frozen envelope schema.
+export const TIER_ORDER = ['user-accepted', 'tests-passed', 'evaluator-verified'];
+export const PickupConfigSchema = z.strictObject({
+    enabled: z.boolean().default(true),
+    /** @deprecated Legacy host compatibility only — a pre-rescope `pickup.json`
+     *  may still send this; evidence-first pickup (rescope §3.3) never reads
+     *  it. Auto-adopt and skill classification were removed from the pickup
+     *  path entirely by R1/R3 (skills are excluded from selection outright,
+     *  not gated by a threshold), so there is no adopt decision left for a
+     *  tier to threshold. */
+    autoAdopt: z.boolean().default(false),
+    /** @deprecated Legacy host compatibility only — same as `autoAdopt`. */
+    autoAdoptTier: z.enum(TIER_ORDER).default('evaluator-verified'),
+    /** @deprecated Legacy host compatibility only — selection has a fixed cap
+     *  (`MAX_SELECTED_PACKETS` in `pickup.ts`), not an operator-configurable one. */
+    maxCandidates: z.number().int().positive().default(3),
+});
+export const DEFAULT_PICKUP_CONFIG = PickupConfigSchema.parse({});
+/** Merge partial input over defaults; a bad autoAdoptTier coerces to default
+ *  (mirrors load_config()'s TIER_ORDER guard). Never throws — bad input → defaults. */
+export function parsePickupConfig(input) {
+    if (input == null || typeof input !== 'object')
+        return { ...DEFAULT_PICKUP_CONFIG };
+    const raw = input;
+    const merged = { ...raw };
+    if (!TIER_ORDER.includes(String(raw.autoAdoptTier))) {
+        delete merged.autoAdoptTier; // fall back to schema default
+    }
+    const result = PickupConfigSchema.safeParse(merged);
+    return result.success ? result.data : { ...DEFAULT_PICKUP_CONFIG };
+}

package/node_modules/@jinn-network/plugin/dist/schemas/session-summary.d.ts

@@ -0,0 +1,17 @@
+/** Assembled at session end() (product design §4.2 legibility requirement — "when Jinn found nothing, it says so"). */
+import { z } from 'zod';
+export declare const SessionSummarySchema: z.ZodObject<{
+    episodeRef: z.ZodString;
+    searchedTerms: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    providedPackets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>>>;
+    eligibility: z.ZodObject<{
+        eligible: z.ZodBoolean;
+        reason: z.ZodString;
+        checkedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    nothingFound: z.ZodBoolean;
+}, z.core.$strict>;
+export type SessionSummary = z.infer<typeof SessionSummarySchema>;

package/node_modules/@jinn-network/plugin/dist/schemas/session-summary.js

@@ -0,0 +1,19 @@
+/** Assembled at session end() (product design §4.2 legibility requirement — "when Jinn found nothing, it says so"). */
+import { z } from 'zod';
+import { EligibilityVerdictSchema } from './eligibility-verdict.js';
+export const SessionSummarySchema = z.strictObject({
+    episodeRef: z.string().min(1),
+    /** Evidence-first pickup facts (rescope §3.6) — the only knowledge-activity
+     *  shape a session summary carries. The pre-rescope `surfacedRefs`/
+     *  `fetchedRefs`/`surfacedHits`/`fetchedHits`/`installedSkillRefs` quintet
+     *  is dropped as of R3+R5 (the host and acceptance gate that consumed it
+     *  have flipped); `Episode.activity` still accepts those fields on read for
+     *  old episode files (rescope §3.6), but no summary emits them again. */
+    searchedTerms: z.array(z.string().min(1)).default([]),
+    providedPackets: z.array(z.strictObject({
+        ref: z.string().min(1),
+        title: z.string().min(1),
+    })).default([]),
+    eligibility: EligibilityVerdictSchema,
+    nothingFound: z.boolean(),
+});

package/node_modules/@jinn-network/plugin/dist/testing/contract-kits.d.ts

@@ -0,0 +1,12 @@
+import type { ContributionPort } from '../ports/contribution-port.js';
+import type { CorpusPort } from '../ports/corpus-port.js';
+import type { EvidencePort } from '../ports/evidence-port.js';
+import type { LocalLearningPort } from '../ports/local-learning-port.js';
+import type { SkillsPort } from '../ports/skills-port.js';
+import type { EpisodeV1 } from '../schemas/episode.js';
+import type { ContributionCandidateV1 } from '../schemas/contribution-candidate.js';
+export declare function describeCorpusPortContract(makeAdapter: () => CorpusPort): void;
+export declare function describeEvidencePortContract(makeAdapter: () => EvidencePort, sampleEpisode: EpisodeV1): void;
+export declare function describeContributionPortContract(makeAdapter: (candidate?: ContributionCandidateV1) => ContributionPort): void;
+export declare function describeLocalLearningPortContract(makeAdapter: () => LocalLearningPort): void;
+export declare function describeSkillsPortContract(makeAdapter: () => SkillsPort): void;

package/node_modules/@jinn-network/plugin/dist/testing/contract-kits.js

@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'vitest';
+function contributionCandidate(overrides = {}) {
+    return {
+        schemaVersion: 'jinn.contribution-candidate.v1',
+        sourceId: 'episode-1',
+        repositorySlug: 'Jinn-Network/mono',
+        baseCommit: '0123456789abcdef',
+        acceptedDiff: 'diff --git a/a.ts b/a.ts\n+fixed\n',
+        testRuns: [],
+        intermediateFailureDiffs: [],
+        skillEvents: [],
+        publishMinedTasksConsent: false,
+        createdAt: '2026-07-15T12:00:00.000Z',
+        ...overrides,
+    };
+}
+export function describeCorpusPortContract(makeAdapter) {
+    describe('CorpusPort contract', () => {
+        it('search() returns an ok PortResult with an array value', async () => {
+            const adapter = makeAdapter();
+            const result = await adapter.search('anything');
+            expect(result.status).toBe('ok');
+            if (result.status === 'ok')
+                expect(Array.isArray(result.value)).toBe(true);
+        });
+        it('get() on an unknown ref returns ok(null)', async () => {
+            const adapter = makeAdapter();
+            const result = await adapter.get('does-not-exist');
+            expect(result).toEqual({ status: 'ok', value: null });
+        });
+    });
+}
+export function describeEvidencePortContract(makeAdapter, sampleEpisode) {
+    describe('EvidencePort contract', () => {
+        it('put() then get() round-trips the episode', async () => {
+            const adapter = makeAdapter();
+            const putResult = await adapter.put(sampleEpisode);
+            expect(putResult.status).toBe('ok');
+            const getResult = await adapter.get(sampleEpisode.episodeId);
+            expect(getResult).toEqual({ status: 'ok', value: sampleEpisode });
+        });
+        it('list() includes a put episode', async () => {
+            const adapter = makeAdapter();
+            await adapter.put(sampleEpisode);
+            const listResult = await adapter.list();
+            expect(listResult.status).toBe('ok');
+            if (listResult.status === 'ok') {
+                expect(listResult.value.map((e) => e.episodeId)).toContain(sampleEpisode.episodeId);
+            }
+        });
+        it('retention() returns a policy result', async () => {
+            const adapter = makeAdapter();
+            const result = await adapter.retention();
+            expect(result.status).toBe('ok');
+            if (result.status === 'ok') {
+                expect(['local-private', 'contribution-eligible']).toContain(result.value.policy);
+            }
+        });
+    });
+}
+export function describeContributionPortContract(makeAdapter) {
+    describe('ContributionPort contract', () => {
+        it('records a candidate locally even when publication consent is disabled', async () => {
+            const input = contributionCandidate();
+            const adapter = makeAdapter(input);
+            const recordResult = await adapter.recordMineable(input);
+            expect(recordResult.status).toBe('ok');
+            if (recordResult.status !== 'ok')
+                return;
+            const statusResult = await adapter.mintStatus(recordResult.value.recordId);
+            expect(statusResult).toEqual({
+                status: 'ok',
+                value: {
+                    localState: 'recorded',
+                    publicationState: 'disabled',
+                    status: 'recorded',
+                },
+            });
+            const ledgerResult = await adapter.ledger();
+            expect(ledgerResult.status).toBe('ok');
+            if (ledgerResult.status === 'ok') {
+                expect(ledgerResult.value).toContainEqual({
+                    recordId: recordResult.value.recordId,
+                    sourceId: 'episode-1',
+                    createdAt: '2026-07-15T12:00:00.000Z',
+                    verifiabilityTier: 'user-accepted',
+                    repositorySlug: 'Jinn-Network/mono',
+                    baseCommit: '0123456789abcdef',
+                    localState: 'recorded',
+                    publicationState: 'disabled',
+                    status: 'recorded',
+                });
+            }
+        });
+        it('requires preview authorization before a consented candidate is queued', async () => {
+            const input = contributionCandidate({
+                publishMinedTasksConsent: true,
+            });
+            const adapter = makeAdapter(input);
+            const recordResult = await adapter.recordMineable(input);
+            if (recordResult.status !== 'ok')
+                throw new Error('recordMineable failed');
+            expect(await adapter.mintStatus(recordResult.value.recordId)).toEqual({
+                status: 'ok',
+                value: {
+                    localState: 'recorded',
+                    publicationState: 'preview-required',
+                    status: 'preview-required',
+                },
+            });
+            const authorizeResult = await adapter.authorize(recordResult.value.recordId);
+            expect(authorizeResult).toEqual({
+                status: 'ok',
+                value: { recordId: recordResult.value.recordId, publicationState: 'queued', status: 'queued' },
+            });
+        });
+        it('veto() changes only publication state and preserves the local record', async () => {
+            const input = contributionCandidate({
+                publishMinedTasksConsent: true,
+            });
+            const adapter = makeAdapter(input);
+            const recordResult = await adapter.recordMineable(input);
+            if (recordResult.status !== 'ok')
+                throw new Error('recordMineable failed');
+            const vetoResult = await adapter.veto(recordResult.value.recordId);
+            expect(vetoResult).toEqual({
+                status: 'ok',
+                value: { recordId: recordResult.value.recordId, publicationState: 'vetoed', status: 'vetoed' },
+            });
+            const statusResult = await adapter.mintStatus(recordResult.value.recordId);
+            expect(statusResult).toEqual({
+                status: 'ok',
+                value: { localState: 'recorded', publicationState: 'vetoed', status: 'vetoed' },
+            });
+        });
+        it('ledger() lists recorded entries', async () => {
+            const input = contributionCandidate();
+            const adapter = makeAdapter(input);
+            await adapter.recordMineable(input);
+            const ledgerResult = await adapter.ledger();
+            expect(ledgerResult.status).toBe('ok');
+            if (ledgerResult.status === 'ok')
+                expect(ledgerResult.value.length).toBeGreaterThan(0);
+        });
+    });
+}
+export function describeLocalLearningPortContract(makeAdapter) {
+    describe('LocalLearningPort contract', () => {
+        it('run() then status() reports the run', async () => {
+            const adapter = makeAdapter();
+            const runResult = await adapter.run({ episodeIds: ['episode-1'] });
+            expect(runResult.status).toBe('ok');
+            if (runResult.status !== 'ok')
+                return;
+            const statusResult = await adapter.status(runResult.value.runId);
+            expect(statusResult.status).toBe('ok');
+        });
+        it('list() includes a started run', async () => {
+            const adapter = makeAdapter();
+            const runResult = await adapter.run({ episodeIds: [] });
+            if (runResult.status !== 'ok')
+                throw new Error('run failed');
+            const listResult = await adapter.list();
+            expect(listResult.status).toBe('ok');
+            if (listResult.status === 'ok') {
+                expect(listResult.value.map((r) => r.runId)).toContain(runResult.value.runId);
+            }
+        });
+        it('skills() is typed when the adapter exposes persisted skill provenance', async () => {
+            const adapter = makeAdapter();
+            if (!adapter.skills)
+                return;
+            const skills = await adapter.skills();
+            expect(skills.status).toBe('ok');
+        });
+    });
+}
+export function describeSkillsPortContract(makeAdapter) {
+    describe('SkillsPort contract', () => {
+        it('install() then list() includes the skill', async () => {
+            const adapter = makeAdapter();
+            const installResult = await adapter.install('org/skill@1.0.0');
+            expect(installResult.status).toBe('ok');
+            const listResult = await adapter.list();
+            expect(listResult.status).toBe('ok');
+            if (listResult.status === 'ok') {
+                expect(listResult.value.map((s) => s.ref)).toContain('org/skill@1.0.0');
+            }
+        });
+        it('uninstall() removes the skill', async () => {
+            const adapter = makeAdapter();
+            await adapter.install('org/skill@1.0.0');
+            await adapter.uninstall('org/skill@1.0.0');
+            const listResult = await adapter.list();
+            expect(listResult.status).toBe('ok');
+            if (listResult.status === 'ok') {
+                expect(listResult.value.map((s) => s.ref)).not.toContain('org/skill@1.0.0');
+            }
+        });
+    });
+}

package/node_modules/@jinn-network/plugin/dist/testing/in-memory-contribution.d.ts

@@ -0,0 +1,93 @@
+import type { ContributionPort, ContributionRecordOptions, ContributionStatusSnapshot } from '../ports/contribution-port.js';
+import { type ContributionCandidateV1 } from '../schemas/contribution-candidate.js';
+export declare class InMemoryContributionPort implements ContributionPort {
+    private readonly records;
+    private counter;
+    recordMineable(candidate: ContributionCandidateV1, options?: ContributionRecordOptions): Promise<{
+        status: "unavailable";
+        reason: string;
+    } | {
+        status: "ok";
+        value: {
+            recordId: string;
+        };
+    } | {
+        status: "degraded";
+        reason: string;
+        value?: {
+            recordId: string;
+        } | undefined;
+    }>;
+    ledger(): Promise<import("../outcome.js").PortResult<{
+        status: import("../index.js").ContributionStatus;
+        localState: import("../index.js").ContributionLocalState;
+        publicationState: import("../index.js").ContributionPublicationState;
+        mintRef?: string;
+        publicationRef?: string;
+        recordId: string;
+        sourceId: string;
+        createdAt: string;
+        verifiabilityTier: "user-accepted" | "tests-passed";
+        repositorySlug: string;
+        baseCommit: string;
+    }[]>>;
+    mintStatus(recordId: string): Promise<{
+        status: "unavailable";
+        reason: string;
+    } | {
+        status: "ok";
+        value: ContributionStatusSnapshot;
+    } | {
+        status: "degraded";
+        reason: string;
+        value?: ContributionStatusSnapshot | undefined;
+    }>;
+    authorize(recordId: string): Promise<{
+        status: "unavailable";
+        reason: string;
+    } | {
+        status: "ok";
+        value: {
+            recordId: string;
+            publicationState: "queued";
+            status: "queued";
+        };
+    } | {
+        status: "degraded";
+        reason: string;
+        value?: {
+            recordId: string;
+            publicationState: "queued";
+            status: "queued";
+        } | undefined;
+    }>;
+    veto(recordId: string): Promise<{
+        status: "unavailable";
+        reason: string;
+    } | {
+        status: "ok";
+        value: {
+            recordId: string;
+            publicationState: "vetoed";
+            status: "vetoed";
+        };
+    } | {
+        status: "degraded";
+        reason: string;
+        value?: {
+            recordId: string;
+            publicationState: "vetoed";
+            status: "vetoed";
+        } | undefined;
+    }>;
+    disableUnpublished(): Promise<import("../outcome.js").PortResult<{
+        recordIds: string[];
+    }>>;
+    /** Testing control for the sidecar-owned forward state. */
+    markMinted(recordId: string, mintRef: string): void;
+    /** Testing control for the sidecar-owned terminal local state. */
+    markRejected(recordId: string): void;
+    /** Testing control for the sidecar-owned outbound state. */
+    markPublished(recordId: string, publicationRef: string): void;
+    getCandidate(recordId: string): ContributionCandidateV1 | undefined;
+}