pi-pstack-native 0.0.0-stage → 1.0.1

package/dist/compatibility/tool.js

@@ -0,0 +1,59 @@
+import { evaluateRound, requireCapability, selectPlaybook, validatePanel } from "./adapter.js";
+import { loadModels } from "../runtime/config.js";
+import { resolveRoleModel, resolvePanelSeats, selectJudgeFromPool, suggestedPanels } from "../models/router.js";
+export function registerSemanticTool(pi) {
+    pi.registerTool({
+        name: 'pstack_semantics', label: 'Pstack semantic adapter',
+        description: 'Check capability mappings, route intents, preflight model panels and validate exact-head/base round receipts. For action panel, omit models to resolve the arena, architect or interrogate panel configured by /setup-pstack. Does not execute workflows, attest evidence or authorize merge.',
+        parameters: { type: 'object', properties: { action: { type: 'string', enum: ['capability', 'route', 'panel', 'round'] }, name: { type: 'string' }, models: { type: 'array', items: { type: 'string' } }, judge: { type: 'string' }, round: { type: 'object', additionalProperties: true } }, required: ['action'], additionalProperties: false },
+        async execute(_id, args, _signal, _update, ctx) {
+            let result;
+            switch (args.action) {
+                case 'capability':
+                    result = requireCapability(args.name);
+                    break;
+                case 'route':
+                    result = { playbook: selectPlaybook(args.name) };
+                    break;
+                case 'panel': {
+                    if (args.models) {
+                        result = validatePanel(args.name, args.models, args.judge);
+                        break;
+                    }
+                    if (!['architect', 'arena', 'interrogate', 'swarm'].includes(args.name))
+                        throw new Error('UNMAPPED_PANEL');
+                    const config = loadModels();
+                    const selectors = args.name === 'swarm' ? [config.workflows?.swarm?.worker ?? config.roles.worker ?? 'inherit-parent'] : config.panels?.[args.name] ?? suggestedPanels(ctx)[args.name];
+                    if (!Array.isArray(selectors) || !selectors.length || selectors.length > 16)
+                        throw new Error(`PANEL_NOT_CONFIGURED: ${args.name}. Run /setup-pstack.`);
+                    const notes = [];
+                    const resolve = (selector) => {
+                        const resolved = resolveRoleModel(ctx, args.name, selector);
+                        notes.push(...resolved.notes);
+                        const model = resolved.model;
+                        if (!model)
+                            throw new Error(`PARENT_MODEL_UNAVAILABLE: ${selector}`);
+                        return `${model.provider}/${model.id}`;
+                    };
+                    const models = args.name === 'swarm' ? selectors.map(resolve) : resolvePanelSeats(ctx, selectors, selectors.length === 1 && args.name === 'interrogate' ? 1 : 2, notes);
+                    let judge;
+                    if (!judge && ['arena', 'architect'].includes(args.name)) {
+                        const pool = args.judge ? [args.judge] : config.panels?.['arena-judges'] ?? suggestedPanels(ctx)['arena-judges'];
+                        if (!Array.isArray(pool) || !pool.length || pool.length > 16)
+                            throw new Error('PANEL_NOT_CONFIGURED: arena-judges. Run /setup-pstack.');
+                        const selection = selectJudgeFromPool(ctx, pool);
+                        notes.push(...selection.notes);
+                        judge = selection.model;
+                    }
+                    result = { ...validatePanel(args.name, models, judge, { independentJudgeSession: true, allowRepeatedModels: true, allowSingleInterrogate: true, allowSkippedJudge: true }), selectors, notes, availability: 'registered-in-current-session', authentication: 'not-checked' };
+                    break;
+                }
+                case 'round':
+                    result = evaluateRound(args.round);
+                    break;
+                default: throw new Error('UNMAPPED_SEMANTIC_ACTION');
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], details: result };
+        },
+    });
+}

package/dist/context/snapshot.d.ts

@@ -0,0 +1,37 @@
+import type { WorkflowEngine } from '../workflow/engine.js';
+export declare function contextSnapshot(engine: WorkflowEngine, sessionId: string, contextTokens?: number, watermark?: number): {
+    schemaVersion: number;
+    at: string;
+    storeRevision: number;
+    contextWarning: string;
+    workflows: {
+        id: string;
+        state: import("../runtime/types.js").WorkflowState;
+        goal: string;
+        budget: import("../api.js").Budget | null;
+        calls: {
+            key: string;
+            execution: import("../runtime/types.js").CallState;
+            brief: {
+                id: string;
+                revision: number;
+                ordersHash: string;
+            } | null;
+            artifactId: string | null;
+            acceptance: string;
+            ledgerId: string | null;
+            usage: import("../api.js").Usage | {
+                tokens: null;
+                cost: null;
+            };
+            nextAction: string;
+        }[];
+    }[];
+    programs: {
+        id: any;
+        state: any;
+        units: any;
+        pendingInbox: any;
+    }[];
+    sourceOfTruth: string;
+};

package/dist/context/snapshot.js

@@ -0,0 +1,12 @@
+import { protocol, hash } from "../runtime/protocol.js";
+export function contextSnapshot(engine, sessionId, contextTokens, watermark = 100000) {
+    const state = protocol();
+    const workflows = engine.list(sessionId);
+    return {
+        schemaVersion: 1, at: new Date().toISOString(), storeRevision: state.revision,
+        contextWarning: contextTokens === undefined ? 'unknown' : contextTokens >= watermark ? 'watermark-exceeded' : 'within-watermark',
+        workflows: workflows.map(w => ({ id: w.id, state: w.state, goal: w.name ?? w.type, budget: w.budget ?? null, calls: Object.values(w.calls).map(c => ({ key: c.key, execution: c.state, brief: c.brief ? { id: c.brief.id, revision: c.brief.revision, ordersHash: hash(c.brief.standingOrders) } : null, artifactId: c.artifactId ?? null, acceptance: c.brief ? engine.accepted(c) ? 'verified' : c.verification?.status === 'passed' ? 'stale' : c.verification?.status ?? 'unknown' : 'legacy-completed', ledgerId: c.verification?.ledgerId ?? null, usage: c.usage ?? { tokens: null, cost: null }, nextAction: c.state === 'pending' ? 'await-dependencies' : c.brief && !engine.accepted(c) ? 'verify-current-artifact' : 'inspect-report' })) })),
+        programs: Object.values(state.programs).filter(p => p.owner === sessionId).map(p => ({ id: p.id, state: p.state, units: p.units.map((u) => ({ key: u.key, state: u.state, workflowId: u.workflowId })), pendingInbox: p.inbox.filter((e) => !e.processed).length })),
+        sourceOfTruth: 'Reload Store and live PR provider on resume. This snapshot is an index, never execution authority.'
+    };
+}

package/dist/contracts/brief.d.ts

@@ -0,0 +1,19 @@
+import type { TaskBrief, TaskReport, Fingerprint } from './types.js';
+export declare function matchPath(path: string, glob: string): boolean;
+export declare class BriefValidationError extends Error {
+    readonly code = "BRIEF_INCOMPLETE";
+    constructor(detail: string);
+}
+export declare function validateBrief(brief: TaskBrief): void;
+export declare function saveBrief(brief: TaskBrief, actor: string, reason: string): TaskBrief;
+export declare function changedPaths(before: Fingerprint, after: Fingerprint, cwd: string): string[];
+export declare function scopeViolations(brief: TaskBrief, paths: string[]): string[];
+export declare function validateReport(value: unknown): TaskReport;
+/** Legacy strings and malformed notes remain blocking; only explicit advisory notes pass. */
+export declare function hasBlockingReportNotes(report: TaskReport): boolean;
+export declare function parseReport(text: string): TaskReport;
+export declare function briefPrompt(brief: TaskBrief): string;
+export declare function validateBudget(budget?: import('./types.js').Budget): void;
+export declare function reportSatisfies(brief: TaskBrief, report: TaskReport): boolean;
+/** Synthesis may paraphrase a finding, but its reproduction must appear in a verifier report. */
+export declare function findingsBackedByVerifiers(report: TaskReport, verifiers: TaskReport[]): boolean;

package/dist/contracts/brief.js

@@ -0,0 +1,198 @@
+import { hash, transact } from "../runtime/protocol.js";
+import { git } from "../artifacts/fingerprint.js";
+export function matchPath(path, glob) {
+    if (glob === '**' || glob === '**/*')
+        return true;
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*\//g, '\u0001').replace(/\*\*/g, '\u0002').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]').replace(/\u0001/g, '(?:.*/)?').replace(/\u0002/g, '.*');
+    return new RegExp(`^${escaped}$`).test(path);
+}
+export class BriefValidationError extends Error {
+    code = 'BRIEF_INCOMPLETE';
+    constructor(detail) { super(`BRIEF_INCOMPLETE: ${detail}`); this.name = 'BriefValidationError'; }
+}
+export function validateBrief(brief) {
+    try {
+        checkBrief(brief);
+    }
+    catch (error) {
+        if (error instanceof BriefValidationError)
+            throw error;
+        throw new BriefValidationError(String(error));
+    }
+}
+function checkBrief(brief) {
+    const errors = [];
+    if (!brief || !['minimal', 'strict'].includes(brief.contractLevel))
+        throw new BriefValidationError('contractLevel');
+    if (!brief.id || !/^[a-zA-Z0-9._-]+$/.test(brief.id) || ['__proto__', 'constructor', 'prototype'].includes(brief.id) || !Number.isInteger(brief.revision) || brief.revision < 1)
+        errors.push('id/revision');
+    if (typeof brief.goal !== 'string' || !brief.goal.trim())
+        errors.push('goal');
+    if (typeof brief.scope?.repoId !== 'string' || !brief.scope.repoId || !Array.isArray(brief.scope.include) || !brief.scope.include.length || !brief.scope.include.every(p => typeof p === 'string') || !Array.isArray(brief.scope.exclude) || !brief.scope.exclude.every(p => typeof p === 'string'))
+        errors.push('scope');
+    if (!Array.isArray(brief.contextRefs))
+        errors.push('contextRefs');
+    if (!Array.isArray(brief.forbidden))
+        errors.push('forbidden');
+    if (!Array.isArray(brief.standingOrders))
+        errors.push('standingOrders');
+    if (brief.reportFormat !== 'task-report-v1')
+        errors.push('reportFormat');
+    if (brief.contractLevel === 'strict' && (!Number.isFinite(brief.timeboxSeconds) || brief.timeboxSeconds <= 0))
+        errors.push('timeboxSeconds');
+    if (!Array.isArray(brief.verification))
+        errors.push('verification');
+    else {
+        const ids = new Set();
+        for (const gate of brief.verification) {
+            if (!gate.id || ids.has(gate.id))
+                errors.push('verification.id');
+            ids.add(gate.id);
+            if (!['command', 'file', 'diff', 'test-report', 'human-approval', 'llm-review'].includes(gate.kind))
+                errors.push(`verification.${gate.id}.kind`);
+            if (gate.command && (!gate.command.length || gate.command.some(x => typeof x !== 'string' || x.includes('\0'))))
+                errors.push(`verification.${gate.id}.command`);
+            if (gate.coverage?.some(p => p.startsWith('/') || p.split('/').includes('..')))
+                errors.push(`verification.${gate.id}.coverage`);
+            if (gate.timeoutSeconds !== undefined && (!Number.isFinite(gate.timeoutSeconds) || gate.timeoutSeconds <= 0))
+                errors.push(`verification.${gate.id}.timeout`);
+        }
+        if (brief.acceptance !== undefined && !Array.isArray(brief.acceptance))
+            errors.push('acceptance');
+        else {
+            if (brief.contractLevel === 'strict' && (!brief.acceptance?.length || !brief.acceptance.some(x => x?.required)))
+                errors.push('acceptance');
+            const acceptanceIds = new Set();
+            for (const ac of brief.acceptance ?? []) {
+                if (!ac || typeof ac.id !== 'string' || !ac.id || acceptanceIds.has(ac.id) || typeof ac.description !== 'string' || !ac.description || typeof ac.required !== 'boolean' || !Array.isArray(ac.gateIds) || !ac.gateIds.length || ac.gateIds.some(id => !ids.has(id))) {
+                    errors.push('acceptance');
+                    continue;
+                }
+                acceptanceIds.add(ac.id);
+                if (ac.required && ac.gateIds.some(id => brief.verification.find(g => g.id === id)?.required === false))
+                    errors.push(`acceptance.${ac.id}.optionalGate`);
+                if (ac.required && ac.gateIds.every(id => brief.verification.find(g => g.id === id)?.kind === 'llm-review'))
+                    errors.push(`acceptance.${ac.id}.machineGate`);
+            }
+        }
+    }
+    for (const p of [...(brief.scope?.include ?? []), ...(brief.scope?.exclude ?? [])])
+        if (p.startsWith('/') || p.split('/').includes('..') || p.includes('\\'))
+            errors.push('scope.relativeGlob');
+    if (errors.length)
+        throw new BriefValidationError([...new Set(errors)].join(', '));
+}
+export function saveBrief(brief, actor, reason) {
+    validateBrief(brief);
+    if (!reason.trim())
+        throw new Error('Brief revision requires reason');
+    return transact('brief-revised', brief.id, actor, s => {
+        const versions = s.briefs[brief.id] ?? [];
+        const last = versions.at(-1);
+        if (last && hash(last) === hash(brief))
+            return last;
+        if (brief.revision !== (last?.revision ?? 0) + 1)
+            throw new Error('BRIEF_REVISION_CONFLICT');
+        versions.push(structuredClone(brief));
+        s.briefs[brief.id] = versions;
+        return brief;
+    });
+}
+export function changedPaths(before, after, cwd) {
+    const working = [...new Set([...Object.keys(before.files), ...Object.keys(after.files)])].filter(p => before.files[p] !== after.files[p]);
+    const staged = git(cwd, ['diff', '--no-renames', '--name-only', '-z', before.indexTree, after.indexTree]).split('\0').filter(Boolean);
+    return [...new Set([...working, ...staged])].sort();
+}
+export function scopeViolations(brief, paths) {
+    return paths.filter(p => !brief.scope.include.some(g => matchPath(p, g)) || brief.scope.exclude.some(g => matchPath(p, g)));
+}
+export function validateReport(value) {
+    const r = value;
+    if (!r || !['completed', 'failed', 'blocked'].includes(r.status) || !r.base || !r.head || !['artifactRefs', 'commandsRun', 'evidenceRefs', 'deviations', 'unresolved', 'nextActions'].every(k => Array.isArray(r[k])))
+        throw new Error('TASK_REPORT_INCOMPLETE');
+    if (![...r.unresolved, ...r.deviations].every(note => typeof note === 'string' || (note && typeof note === 'object' && ['blocking', 'advisory'].includes(note.severity) && typeof note.description === 'string' && Boolean(note.description.trim()))))
+        throw new Error('TASK_REPORT_INCOMPLETE');
+    return r;
+}
+/** Legacy strings and malformed notes remain blocking; only explicit advisory notes pass. */
+export function hasBlockingReportNotes(report) {
+    return !Array.isArray(report.unresolved) || !Array.isArray(report.deviations) || [...report.unresolved, ...report.deviations].some(note => typeof note !== 'object' || note === null || note.severity !== 'advisory' || typeof note.description !== 'string' || !note.description.trim());
+}
+export function parseReport(text) {
+    const block = text.match(/```(?:task-report|json)\s*\n([\s\S]*?)```/);
+    return validateReport(JSON.parse(block ? block[1] : text));
+}
+export function briefPrompt(brief) {
+    const extra = {
+        evaluation: 'Include evaluation: [{"criterion": "...", "score": 0, "evidence": ["..."], "weaknesses": [], "selectedParts": []}] for every required criterion; scores must be 0 to 10 and evidence must be nonempty.',
+        'cross-evaluation': 'Include crossEvaluation: [{"candidate":"candidate-1", "criterion":"...", "score":0, "evidence":["file:line"], "weaknesses":[], "selectedParts":[]}] for every candidate and every required criterion, with scores 0 to 10 and nonempty evidence. Include selection: {"candidates":["candidate-1"], "selectedParts":[]} selecting exactly one base.',
+        selection: 'Include selection: {"candidates": ["..."], "selectedParts": []}, naming candidates from the brief.',
+        ranking: 'Include ranking: [{"candidate":"...", "rank":1, "reason":"..."}] for every candidate exactly once, with unique consecutive ranks starting at 1.',
+        review: 'Include findings: [{"severity": "low", "location": "...", "description": "...", "evidence": "..."}]; severity is critical, high, medium, or low. Use [] when there are no findings.',
+        'repro-review': 'Include findings: [{"severity":"high", "location":"...", "description":"...", "evidence":"...", "reproduction":{"command":["executable","arg"], "observed":"actual output", "expected":"intent requires this output"}}]. Include only findings proven by a run. Use [] when none survive.',
+        coverage: 'Include coverage: {"completed": ["..."], "unresolved": []}, listing completed required slices.',
+    };
+    return `\n\nAuthoritative Task Brief (${brief.id} revision ${brief.revision}, orders ${hash(brief.standingOrders)}):\n${JSON.stringify(brief, null, 2)}\nReturn one fenced JSON task report with all fields: {"status":"completed", "artifactRefs":[], "base":"<starting full git commit SHA>", "head":"<current full git commit SHA>", "commandsRun":[], "evidenceRefs":[], "deviations":[], "unresolved":[], "nextActions":[]}. status must be exactly one of completed, failed, or blocked (not a synonym). All six array fields are required, even when empty; commandsRun entries are arrays of command arguments. Use full commit SHAs from git rev-parse (40 hex characters for SHA-1 or 64 for SHA-256), not abbreviations or invented values. For each unresolved item or deviation, use {"severity":"advisory","description":"..."} or {"severity":"blocking","description":"..."}; use blocking when it affects acceptance or its impact is uncertain, and advisory only for non-blocking information supported by evidence. Legacy plain strings are blocking. ${brief.reportRequirements ? extra[brief.reportRequirements.kind] : ''} Do not claim verification from narrative alone.`;
+}
+export function validateBudget(budget) {
+    if (!budget)
+        return;
+    for (const [key, value] of Object.entries(budget))
+        if (!['maxTokens', 'maxCost', 'maxTimeSeconds'].includes(key) || !Number.isFinite(value) || value <= 0)
+            throw new Error(`INVALID_BUDGET: ${key}`);
+}
+export function reportSatisfies(brief, report) {
+    const req = brief.reportRequirements;
+    if (!req)
+        return true;
+    if (req.kind === 'evaluation')
+        return Boolean(report.evaluation && req.criteria?.every(c => report.evaluation.some(e => e.criterion === c && Number.isFinite(e.score) && e.score >= 0 && e.score <= 10 && e.evidence?.length && Array.isArray(e.weaknesses) && Array.isArray(e.selectedParts))));
+    if (req.kind === 'cross-evaluation') {
+        if (!req.candidates?.length || !req.criteria?.length || !Array.isArray(report.crossEvaluation) ||
+            !Array.isArray(report.selection?.candidates) || report.selection.candidates.length !== 1 ||
+            !req.candidates.includes(report.selection.candidates[0]) || !Array.isArray(report.selection.selectedParts))
+            return false;
+        const pairs = new Set();
+        for (const entry of report.crossEvaluation) {
+            if (!entry || !req.candidates.includes(entry.candidate) || !req.criteria.includes(entry.criterion) ||
+                !Number.isFinite(entry.score) || entry.score < 0 || entry.score > 10 ||
+                !Array.isArray(entry.evidence) || !entry.evidence.some(value => typeof value === 'string' && value.trim()) ||
+                !Array.isArray(entry.weaknesses) || !Array.isArray(entry.selectedParts))
+                return false;
+            const pair = JSON.stringify([entry.candidate, entry.criterion]);
+            if (pairs.has(pair))
+                return false;
+            pairs.add(pair);
+        }
+        return req.candidates.every(candidate => req.criteria.every(criterion => pairs.has(JSON.stringify([candidate, criterion]))));
+    }
+    if (req.kind === 'selection')
+        return Boolean(report.selection?.candidates.length && report.selection.candidates.every(c => req.candidates?.includes(c)) && Array.isArray(report.selection.selectedParts));
+    if (req.kind === 'ranking') {
+        if (!req.candidates?.length || !Array.isArray(report.ranking) || report.ranking.length !== req.candidates.length)
+            return false;
+        const candidates = new Set(), ranks = new Set();
+        for (const item of report.ranking) {
+            if (!item || !req.candidates.includes(item.candidate) || candidates.has(item.candidate) || !Number.isInteger(item.rank) || item.rank < 1 || item.rank > req.candidates.length || ranks.has(item.rank) || typeof item.reason !== 'string' || !item.reason.trim())
+                return false;
+            candidates.add(item.candidate);
+            ranks.add(item.rank);
+        }
+        return candidates.size === req.candidates.length && ranks.size === req.candidates.length;
+    }
+    if (req.kind === 'review')
+        return Array.isArray(report.findings) && report.findings.every(f => ['critical', 'high', 'medium', 'low'].includes(f.severity) && Boolean(f.location && f.description && f.evidence));
+    if (req.kind === 'repro-review')
+        return Array.isArray(report.findings) && report.findings.every(f => ['critical', 'high', 'medium', 'low'].includes(f.severity) && Boolean(f.location && f.description && f.evidence) && Array.isArray(f.reproduction?.command) && f.reproduction.command.length > 0 && f.reproduction.command.every(x => typeof x === 'string' && x.trim().length > 0) && typeof f.reproduction.observed === 'string' && f.reproduction.observed.trim().length > 0 && typeof f.reproduction.expected === 'string' && f.reproduction.expected.trim().length > 0);
+    if (req.kind === 'coverage')
+        return Boolean(report.coverage && !report.coverage.unresolved.length && req.slices?.every(c => report.coverage.completed.includes(c)));
+    return false;
+}
+/** Synthesis may paraphrase a finding, but its reproduction must appear in a verifier report. */
+export function findingsBackedByVerifiers(report, verifiers) {
+    if (!Array.isArray(report.findings))
+        return false;
+    const key = (finding) => finding.reproduction && JSON.stringify([finding.reproduction.command, finding.reproduction.observed, finding.reproduction.expected]);
+    const confirmed = new Set(verifiers.flatMap(value => value.findings ?? []).map(key).filter(Boolean));
+    return report.findings.every(finding => Boolean(key(finding) && confirmed.has(key(finding))));
+}

package/dist/contracts/types.d.ts

@@ -0,0 +1,192 @@
+export type GateStatus = 'pending' | 'running' | 'passed' | 'failed' | 'blocked' | 'stale';
+export interface GateSpec {
+    id: string;
+    kind: 'command' | 'file' | 'diff' | 'test-report' | 'human-approval' | 'llm-review';
+    required?: boolean;
+    command?: string[];
+    timeoutSeconds?: number;
+    sideEffect?: 'none' | 'local' | 'remote';
+    path?: string;
+    pattern?: string;
+    format?: 'junit' | 'tap';
+    maxFiles?: number;
+    coverage?: string[];
+    category?: 'behavior' | 'typecheck' | 'review';
+}
+export type TaskBrief = BriefFields & ({
+    contractLevel: 'minimal';
+    acceptance?: Acceptance[];
+} | {
+    contractLevel: 'strict';
+    acceptance: Acceptance[];
+});
+export interface Acceptance {
+    id: string;
+    description: string;
+    required: boolean;
+    gateIds: string[];
+}
+interface BriefFields {
+    id: string;
+    revision: number;
+    goal: string;
+    scope: {
+        include: string[];
+        exclude: string[];
+        repoId: string;
+    };
+    contextRefs: string[];
+    verification: GateSpec[];
+    timeboxSeconds?: number;
+    forbidden: string[];
+    standingOrders: string[];
+    reportFormat: 'task-report-v1';
+    reportRequirements?: {
+        kind: 'evaluation' | 'cross-evaluation' | 'selection' | 'ranking' | 'review' | 'repro-review' | 'coverage';
+        criteria?: string[];
+        candidates?: string[];
+        slices?: string[];
+    };
+}
+export type ReportNote = string | {
+    severity: 'blocking' | 'advisory';
+    description: string;
+};
+export interface TaskReport {
+    status: 'completed' | 'blocked' | 'failed';
+    artifactRefs: string[];
+    base: string;
+    head: string;
+    commandsRun: string[][];
+    evidenceRefs: string[];
+    deviations: ReportNote[];
+    unresolved: ReportNote[];
+    nextActions: string[];
+    evaluation?: {
+        criterion: string;
+        score: number;
+        evidence: string[];
+        weaknesses: string[];
+        selectedParts: string[];
+    }[];
+    crossEvaluation?: {
+        candidate: string;
+        criterion: string;
+        score: number;
+        evidence: string[];
+        weaknesses: string[];
+        selectedParts: string[];
+    }[];
+    selection?: {
+        candidates: string[];
+        selectedParts: string[];
+    };
+    ranking?: {
+        candidate: string;
+        rank: number;
+        reason: string;
+    }[];
+    findings?: {
+        severity: 'critical' | 'high' | 'medium' | 'low';
+        location: string;
+        description: string;
+        evidence: string;
+        reproduction?: {
+            command: string[];
+            observed: string;
+            expected: string;
+        };
+    }[];
+    coverage?: {
+        completed: string[];
+        unresolved: string[];
+    };
+}
+export interface Budget {
+    maxTokens?: number;
+    maxCost?: number;
+    maxTimeSeconds?: number;
+}
+export interface Usage {
+    tokens: number | null;
+    cost: number | null;
+    elapsedMs: number;
+}
+export interface Fingerprint {
+    repoId: string;
+    kind: 'working' | 'committed';
+    commitSha: string;
+    treeSha: string;
+    workspaceDigest: string;
+    indexTree: string;
+    policyVersion: 1;
+    files: Record<string, string>;
+    dirty: boolean;
+}
+export interface BaselineOwner {
+    briefId: string;
+    briefRevision: number;
+    workflowId?: string;
+    callKey?: string;
+}
+export interface Artifact {
+    id: string;
+    cwd: string;
+    fingerprint: Fingerprint;
+    parents: string[];
+    producer?: string;
+    owner?: BaselineOwner;
+    createdAt: string;
+}
+export interface Evidence {
+    id: string;
+    gateId: string;
+    gateDefinitionHash: string;
+    status: GateStatus;
+    reason?: string;
+    command?: string[];
+    cwd: string;
+    exitCode?: number | null;
+    startedAt: string;
+    finishedAt: string;
+    artifactId: string;
+    logPath: string;
+    checksum: string;
+    actor: string;
+    environmentHash: string;
+}
+export interface Ledger {
+    id: string;
+    artifactId: string;
+    fingerprint: Fingerprint;
+    evidenceRefs: string[];
+    contractAccepted: boolean;
+    gateIds: string[];
+    gateDefinitionHash: string;
+    status: GateStatus;
+    verdict: 'unit-test-verified' | 'type-check-only' | 'verifier-blocked' | 'verifier-failed' | 'not-verified';
+    verifiedAt: string;
+    verifiedBy: string;
+    executionNonce: string;
+    diffBase?: {
+        kind: 'pr' | 'fingerprint';
+        commitSha: string;
+        fingerprintHash?: string;
+        refreshed: boolean;
+    };
+    pr?: {
+        repoId: string;
+        number: number;
+        headSha: string;
+        baseSha?: string;
+    };
+}
+export interface Event {
+    id: string;
+    at: string;
+    actor: string;
+    type: string;
+    subject: string;
+    data: unknown;
+}
+export {};

package/dist/contracts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/delivery/frontier.d.ts

@@ -0,0 +1,61 @@
+import type { PRProvider, PullRequest } from './provider.js';
+export interface StackSpec {
+    id: string;
+    repoId: string;
+    repo: string;
+    numbers: number[];
+    owner: string;
+    requireReview?: boolean;
+    requireBehavior?: boolean;
+    rootBase?: string;
+}
+export interface Frontier extends StackSpec {
+    generation: number;
+    digest: string;
+    prs: PullRequest[];
+    checkedAt: string;
+}
+export declare function refresh(spec: StackSpec, provider: PRProvider): Promise<Frontier>;
+export declare function eligibility(f: Frontier): {
+    number: number;
+    eligible: boolean;
+    blockers: string[];
+}[];
+export declare function authorizeMerge(f: Frontier, number: number, actor: string): string;
+export declare function ship(spec: StackSpec, provider: PRProvider, options?: {
+    token?: string;
+    dryRun?: boolean;
+}): Promise<unknown>;
+/** Native snapshot states, not fabricated Cursor watcher verdicts. No merging or polling. */
+export declare function watchFrontier(f: Frontier, previous?: {
+    number: number;
+    headSha: string;
+    digest: string;
+}): {
+    state: string;
+    frontier: null;
+    digest: string;
+    headSha?: undefined;
+    blockers?: undefined;
+    autoMergeRequested?: undefined;
+    queueState?: undefined;
+    stopBeforeMerge?: undefined;
+} | {
+    state: string;
+    frontier: number;
+    digest: string;
+    headSha?: undefined;
+    blockers?: undefined;
+    autoMergeRequested?: undefined;
+    queueState?: undefined;
+    stopBeforeMerge?: undefined;
+} | {
+    state: string;
+    frontier: number;
+    headSha: string;
+    digest: string;
+    blockers: string[];
+    autoMergeRequested: boolean;
+    queueState: string;
+    stopBeforeMerge: boolean;
+};