pi-pstack-native 0.0.0-stage → 1.0.0

package/src/contracts/brief.ts

@@ -0,0 +1,144 @@
+import { hash, transact } from '../runtime/protocol.ts';
+import { git } from '../artifacts/fingerprint.ts';
+import type { TaskBrief, TaskReport, Fingerprint } from './types.ts';
+export function matchPath(path: string, glob: string): boolean {
+  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 {
+  readonly code = 'BRIEF_INCOMPLETE';
+  constructor(detail: string) { super(`BRIEF_INCOMPLETE: ${detail}`); this.name = 'BriefValidationError'; }
+}
+export function validateBrief(brief: TaskBrief): void {
+  try { checkBrief(brief); }
+  catch(error) { if(error instanceof BriefValidationError) throw error; throw new BriefValidationError(String(error)); }
+}
+function checkBrief(brief: TaskBrief): void {
+  const errors: string[] = [];
+  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<string>();
+    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<string>();
+      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: TaskBrief, actor: string, reason: string): TaskBrief {
+  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: Fingerprint, after: Fingerprint, cwd: string): string[] {
+  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: TaskBrief, paths: string[]): string[] {
+  return paths.filter(p=>!brief.scope.include.some(g=>matchPath(p,g)) || brief.scope.exclude.some(g=>matchPath(p,g)));
+}
+export function validateReport(value: unknown): TaskReport {
+  const r = value as TaskReport;
+  if (!r || !['completed','failed','blocked'].includes(r.status) || !r.base || !r.head || !['artifactRefs','commandsRun','evidenceRefs','deviations','unresolved','nextActions'].every(k=>Array.isArray((r as any)[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: TaskReport): boolean {
+  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: string): TaskReport {
+  const block = text.match(/```(?:task-report|json)\s*\n([\s\S]*?)```/);
+  return validateReport(JSON.parse(block ? block[1] : text));
+}
+export function briefPrompt(brief: TaskBrief): string {
+  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?: import('./types.ts').Budget): void {
+  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: TaskBrief, report: TaskReport): boolean {
+  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<string>();
+    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<string>(), ranks = new Set<number>();
+    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: TaskReport, verifiers: TaskReport[]): boolean {
+  if (!Array.isArray(report.findings)) return false;
+  const key = (finding: NonNullable<TaskReport['findings']>[number]) => 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/src/contracts/types.ts

@@ -0,0 +1,57 @@
+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 }

package/src/delivery/frontier.ts

@@ -0,0 +1,87 @@
+import { hash, protocol, transact, uid } from '../runtime/protocol.ts';
+import { ledgerCurrent } from '../verification/runner.ts';
+import type { PRProvider, PullRequest } from './provider.ts';
+// GitHub reports CLEAN only when the base and the required checks are settled. Every other merge
+// state, and a missing one, needs a human look before shipping.
+const CLEAN_MERGE_STATE='CLEAN';
+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 async function refresh(spec:StackSpec,provider:PRProvider):Promise<Frontier> {
+  if(!/^[a-zA-Z0-9._-]+$/.test(spec.id) || ['__proto__','constructor','prototype'].includes(spec.id))throw new Error('INVALID_STACK_ID');
+  if(!spec.numbers.length || new Set(spec.numbers).size!==spec.numbers.length)throw new Error('INVALID_STACK');
+  const prs:PullRequest[]=[]; for(const number of spec.numbers)prs.push(await provider.read(spec.repo,number));
+  if(prs.some((p,i)=>p.repo!==spec.repo || p.number!==spec.numbers[i] || !p.headSha || !p.baseSha))throw new Error('STATE_UNCERTAIN');
+  // A dependent base must equal the preceding head before that predecessor is merged.
+  for(let i=1;i<prs.length;i++)if(prs[i-1].state!=='MERGED' && (prs[i].baseSha!==prs[i-1].headSha || Boolean(prs[i-1].headRef && prs[i].baseRef!==prs[i-1].headRef)))throw new Error('STACK_TOPOLOGY_MISMATCH');
+  return transact('frontier-refreshed',spec.id,'provider',s=>{
+    const old=s.frontiers[spec.id] as Frontier|undefined;
+    if(old && (old.owner!==spec.owner || old.repo!==spec.repo || old.repoId!==spec.repoId))throw new Error('STACK_IDENTITY_CONFLICT');
+    for(const e of Object.values(s.ledgers)) {
+      const p=prs.find(p=>e.pr?.repoId===spec.repoId && e.pr.number===p.number);
+      if(p && (!e.diffBase || e.diffBase.commitSha!==p.baseSha || e.pr!.headSha!==p.headSha))s.invalidations[e.id]={at:new Date().toISOString(),reason:'PR_BASE_OR_HEAD_CHANGED'};
+    }
+    // The shipping trunk is operator input, never a property of the PR under test. A persisted
+    // value wins so a later refresh cannot retarget the trunk silently.
+    const rootBase=old?.rootBase ?? spec.rootBase;
+    if(!rootBase)throw new Error('STACK_ROOT_BASE_REQUIRED');
+    if(old?.rootBase && spec.rootBase && spec.rootBase!==old.rootBase)throw new Error('STACK_ROOT_BASE_CHANGED');
+    const digest=hash({prs,rootBase,requireReview:spec.requireReview!==false,requireBehavior:spec.requireBehavior!==false});
+    const f:Frontier={...spec,rootBase,prs,digest,generation:(old?.generation ?? 0)+(old?.digest===digest?0:1),checkedAt:new Date().toISOString()};s.frontiers[spec.id]=f;return f;
+  });
+}
+export function eligibility(f:Frontier):{number:number;eligible:boolean;blockers:string[]}[] {
+  const s=protocol();let lower=false;
+  return f.prs.map(p=>{
+    if(p.state==='MERGED')return {number:p.number,eligible:false,blockers:['ALREADY_MERGED']};
+    const blockers:string[]=[];
+    if(lower)blockers.push('LOWER_UNMERGED');
+    else if(f.rootBase && p.baseRef!==f.rootBase)blockers.push('FRONTIER_BASE_NOT_TRUNK');
+    lower=true;
+    if(p.state!=='OPEN')blockers.push('PR_NOT_OPEN');
+    // Runtime callers can be plain JavaScript, so absent provider fields must still block.
+    if(p.draft!==false)blockers.push('PR_DRAFT');
+    if(p.reviewThreads?.status!=='checked')blockers.push('REVIEW_THREADS_NOT_CHECKED');
+    else if(p.reviewThreads.unresolved>0)blockers.push('UNRESOLVED_REVIEW_THREADS');
+    if(p.mergeState!==CLEAN_MERGE_STATE)blockers.push(`MERGE_STATE_${p.mergeState ?? 'MISSING'}`);
+    if(p.mergeable!=='MERGEABLE')blockers.push(p.mergeable==='CONFLICTING'?'CONFLICT':'STATE_UNCERTAIN');
+    if(p.review==='changes-requested' || f.requireReview!==false && p.review!=='approved')blockers.push('REVIEW_REQUIRED');
+    if(p.ci!=='passed')blockers.push('CI_NOT_PASSED');
+    const entries=Object.values(s.ledgers).filter(e=>e.pr?.repoId===f.repoId && e.pr.number===p.number && e.pr.headSha===p.headSha && e.fingerprint.kind==='committed' && e.fingerprint.commitSha===p.headSha);
+    if(!entries.some(e=>e.diffBase?.commitSha===p.baseSha && e.contractAccepted && ledgerCurrent(e,e.fingerprint) && (f.requireBehavior===false || e.verdict==='unit-test-verified')))blockers.push('CURRENT_VERIFICATION_REQUIRED');
+    return {number:p.number,eligible:blockers.length===0,blockers};
+  });
+}
+export function authorizeMerge(f:Frontier,number:number,actor:string):string {
+  if(actor!=='human-cli')throw new Error('HUMAN_AUTHORIZATION_REQUIRED');
+  const token=uid('approval');transact('merge-authorized',f.id,actor,s=>{s.approvals[token]={stackId:f.id,number,digest:f.digest,generation:f.generation,expiresAt:Date.now()+5*60_000,used:false};return {token,number};});return token;
+}
+export async function ship(spec:StackSpec,provider:PRProvider,options:{token?:string;dryRun?:boolean}={}):Promise<unknown> {
+  const f=await refresh(spec,provider);const decisions=eligibility(f);
+  if(options.dryRun!==false)return {frontier:f,decisions,dryRun:true};
+  const approval=options.token?protocol().approvals[options.token]:undefined;
+  if(!approval || approval.stackId!==f.id || approval.digest!==f.digest || approval.generation!==f.generation || approval.used || approval.expiresAt<Date.now())throw new Error('AUTHORIZATION_MISSING_OR_STALE');
+  const target=f.prs.find(p=>p.number===approval.number)!;
+  if(!decisions.find(d=>d.number===target?.number)?.eligible)throw new Error('SHIPPING_BLOCKED');
+  // Query twice, then use provider's server-side expected-head precondition.
+  const checked=await refresh(spec,provider);
+  if(checked.digest!==f.digest || checked.generation!==f.generation)throw new Error('FRONTIER_CHANGED');
+  transact('merge-requested',f.id,'shipping-gate',s=>{
+    const a=s.approvals[options.token!];if(a.used)throw new Error('AUTHORIZATION_CONSUMED');a.used=true;
+    return {number:target.number,head:target.headSha};
+  });
+  await provider.merge(target);
+  const actual=await provider.read(spec.repo,target.number);
+  if(actual.state!=='MERGED')throw new Error('MERGE_UNCONFIRMED');
+  transact('merge-confirmed',f.id,'provider',()=>({number:actual.number,head:actual.headSha}));
+  return {merged:actual.number,frontier:await refresh(spec,provider)};
+}
+
+/** Native snapshot states, not fabricated Cursor watcher verdicts. No merging or polling. */
+export function watchFrontier(f:Frontier,previous?:{number:number;headSha:string;digest:string}) {
+ const target=f.prs.find(p=>p.state!=='MERGED');
+ if(!target)return {state:'complete',frontier:null,digest:f.digest};
+ if(target.state==='CLOSED')return {state:'closed',frontier:target.number,digest:f.digest};
+ const decision=eligibility(f).find(d=>d.number===target.number)!;
+ const advanced=previous && previous.number!==target.number;
+ return {state:advanced?'advance':decision.eligible?'reviewable':'waiting',frontier:target.number,headSha:target.headSha,digest:f.digest,blockers:decision.blockers,autoMergeRequested:target.autoMergeRequested ?? false,queueState:'not-claimed',stopBeforeMerge:true};
+}

package/src/delivery/git.ts

@@ -0,0 +1,9 @@
+import { git } from '../artifacts/fingerprint.ts';
+export function githubRepository(cwd:string):string {
+  const remote=git(cwd,['remote','get-url','origin']);
+  const match=remote.match(/^(?:https:\/\/(?:[^/@]+@)?github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/);
+  if(!match)throw new Error('GITHUB_REPOSITORY_UNCONFIRMED');return match[1];
+}
+export function assertGitHubRepository(cwd:string,repo:string):void {
+  if(githubRepository(cwd).toLowerCase()!==repo.toLowerCase())throw new Error('PROVIDER_REPOSITORY_MISMATCH');
+}

package/src/delivery/prepare.ts

@@ -0,0 +1,23 @@
+import { assertGitHubRepository } from "./git.ts";
+import { writeFileSync } from 'node:fs';
+import { homePath } from '../runtime/home.ts';
+import { protocol, uid, transact } from '../runtime/protocol.ts';
+import { fingerprint } from '../artifacts/fingerprint.ts';
+import { ledgerCurrent } from '../verification/runner.ts';
+import type { GitHubCLI } from './provider.ts';
+export function preparePR(cwd:string,ledgerId:string,options:{repo:string;base:string;head:string;title:string}) {
+  assertGitHubRepository(cwd,options.repo);
+  const l=protocol().ledgers[ledgerId];const current=fingerprint(cwd,'committed');
+  if(!l || !l.contractAccepted || l.fingerprint.kind!=='committed' || !ledgerCurrent(l,current))throw new Error('CURRENT_ACCEPTED_COMMIT_REQUIRED');
+  if(!options.title.trim() || !/^[\w.-]+\/[\w.-]+$/.test(options.repo))throw new Error('INVALID_PR_DETAILS');
+  const plan={id:uid('prplan'),...options,headSha:current.commitSha,ledgerId,evidence:l.evidenceRefs,body:`${options.title}\n\nVerified commit: ${current.commitSha}\nVerification: ${l.verdict}\nLedger: ${l.id}\nEvidence: ${l.evidenceRefs.join(', ')}\n`};
+  transact('pr-prepared',plan.id,'delivery',()=>plan);return plan;
+}
+export async function openPreparedPR(cwd:string,plan:ReturnType<typeof preparePR>,provider:GitHubCLI,approve=false):Promise<unknown> {
+  if(!approve)return {plan,dryRun:true};
+  preparePR(cwd,plan.ledgerId,plan);
+  if(await provider.branchHead(plan.repo,plan.head)!==plan.headSha)throw new Error('REMOTE_BRANCH_NOT_VERIFIED');
+  const path=homePath(`${plan.id}.md`);writeFileSync(path,plan.body,{mode:0o600});
+  const url=await provider.open(plan.repo,plan.base,plan.head,plan.title,path);
+  transact('pr-opened',plan.id,'human-cli',()=>({url,headSha:plan.headSha}));return {url};
+}

package/src/delivery/provider.ts

@@ -0,0 +1,41 @@
+import { collectReviewThreads, REVIEW_THREADS_QUERY, type ReviewThreadSummary } from './review-threads.ts';
+import { execFileSync } from 'node:child_process';
+export interface PullRequest {
+  headRef?:string; draft:boolean; mergeState:string; autoMergeRequested?:boolean; reviewThreads?:ReviewThreadSummary;
+  number:number; repo:string; headSha:string; baseSha:string; baseRef:string; state:'OPEN'|'MERGED'|'CLOSED';
+  mergeable:'MERGEABLE'|'CONFLICTING'|'UNKNOWN'; ci:'passed'|'failed'|'pending'|'unknown'; review:'approved'|'changes-requested'|'pending';
+}
+export interface PRProvider { read(repo:string,number:number):Promise<PullRequest>; merge(pr:PullRequest):Promise<void> }
+export class GitHubCLI implements PRProvider {
+  private readonly execute?: (args:string[])=>string;
+  constructor(execute?: (args:string[])=>string){this.execute=execute;}
+  private gh(args:string[]):string {if(this.execute)return this.execute(args);return execFileSync('gh',args,{encoding:'utf8',timeout:30000,maxBuffer:4*1024*1024});}
+  async read(repo:string,number:number):Promise<PullRequest> {
+    if(!/^[\w.-]+\/[\w.-]+$/.test(repo) || !Number.isSafeInteger(number) || number<1)throw new Error('Invalid GitHub PR');
+    let p=JSON.parse(this.gh(['pr','view',String(number),'--repo',repo,'--json','number,headRefOid,headRefName,baseRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,autoMergeRequest']));
+    const [owner,name]=repo.split('/');
+    const reviewThreads=await collectReviewThreads(async cursor=>JSON.parse(this.gh(['api','graphql','-f',`query=${REVIEW_THREADS_QUERY}`,'-F',`owner=${owner}`,'-F',`repo=${name}`,'-F',`number=${number}`,...(cursor ? ['-f',`after=${cursor}`]:[])])));
+    const confirmed=JSON.parse(this.gh(['pr','view',String(number),'--repo',repo,'--json','number,headRefOid,headRefName,baseRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,autoMergeRequest']));
+    if(confirmed.headRefOid!==p.headRefOid || confirmed.baseRefOid!==p.baseRefOid || confirmed.state!==p.state)throw new Error('PR_CHANGED_DURING_READ');
+    p=confirmed;
+    const checks=p.statusCheckRollup;
+    const ci = !Array.isArray(checks) || !checks.length ? 'unknown' : checks.some((c:any)=>['FAILURE','ERROR','CANCELLED','TIMED_OUT','ACTION_REQUIRED'].includes(c.conclusion ?? c.state))?'failed':checks.every((c:any)=>['SUCCESS'].includes(c.conclusion ?? c.state))?'passed':'pending';
+    return {headRef:p.headRefName,draft:p.isDraft,mergeState:p.mergeStateStatus ?? 'UNKNOWN',autoMergeRequested:p.autoMergeRequest!=null,reviewThreads,number:p.number,repo,headSha:p.headRefOid,baseSha:p.baseRefOid,baseRef:p.baseRefName,state:p.state,mergeable:p.mergeable,ci,review:p.reviewDecision==='APPROVED'?'approved':p.reviewDecision==='CHANGES_REQUESTED'?'changes-requested':'pending'};
+  }
+  async merge(pr:PullRequest):Promise<void> {
+    this.gh(['pr','merge',String(pr.number),'--repo',pr.repo,'--merge','--match-head-commit',pr.headSha]);
+  }
+  async branchHead(repo:string,branch:string):Promise<string> {
+    const r=JSON.parse(this.gh(['api',`repos/${repo}/git/ref/heads/${encodeURIComponent(branch)}`]));
+    if(r.object?.type!=='commit' || !r.object.sha)throw new Error('REMOTE_BRANCH_UNCERTAIN');return r.object.sha;
+  }
+  async find(repo:string,head:string):Promise<number|null> {
+    if(!/^[\w.-]+\/[\w.-]+$/.test(repo) || !head || head.startsWith('-'))throw new Error('INVALID_PR_LOOKUP');
+    const prs=JSON.parse(this.gh(['pr','list','--repo',repo,'--head',head,'--state','all','--limit','100','--json','number']));
+    if(!Array.isArray(prs) || prs.length>1)throw new Error('PR_LOOKUP_AMBIGUOUS');
+    return prs[0]?.number ?? null;
+  }
+  async open(repo:string,base:string,head:string,title:string,bodyFile:string):Promise<string> {
+    return this.gh(['pr','create','--repo',repo,'--base',base,'--head',head,'--title',title,'--body-file',bodyFile]).trim();
+  }
+}

package/src/delivery/review-threads.ts

@@ -0,0 +1,28 @@
+export interface ReviewThread {id:string;resolved:boolean;author:string|null;createdAt:string|null}
+export interface ReviewThreadSummary {status:'checked';unresolved:number;bugbotUnresolved:number;total:number}
+export const REVIEW_THREADS_QUERY = `query($owner:String!,$repo:String!,$number:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id isResolved comments(first:1){nodes{createdAt author{login}}}}}}}}`;
+export function parseReviewThreadPage(value:any):{threads:ReviewThread[];next:string|null} {
+ const page=value?.data?.repository?.pullRequest?.reviewThreads;
+ if(value?.errors?.length || !page || !Array.isArray(page.nodes) || page.nodes.length>100 || typeof page.pageInfo?.hasNextPage!=='boolean')throw new Error('REVIEW_THREADS_UNAVAILABLE');
+ const threads=page.nodes.map((node:any)=>{
+  if(typeof node.id!=='string' || !node.id || typeof node.isResolved!=='boolean' || !Array.isArray(node.comments?.nodes))throw new Error('REVIEW_THREADS_UNAVAILABLE');
+  const first=node.comments.nodes[0];return {id:node.id,resolved:node.isResolved,author:first?.author?.login ?? null,createdAt:first?.createdAt ?? null};
+ });
+ const next=page.pageInfo.hasNextPage?page.pageInfo.endCursor:null;
+ if(page.pageInfo.hasNextPage && (typeof next!=='string' || !next || next.length>2048))throw new Error('REVIEW_THREADS_CURSOR_INVALID');
+ return {threads,next};
+}
+export async function collectReviewThreads(read:(cursor:string|null)=>Promise<unknown>):Promise<ReviewThreadSummary> {
+ const cursors=new Set<string>(),threads=new Map<string,ReviewThread>();let cursor:string|null=null,pages=0;
+ do {
+  if(++pages>50)throw new Error('REVIEW_THREADS_PAGE_LIMIT');
+  const page=parseReviewThreadPage(await read(cursor));
+  for(const t of page.threads) {
+   const previous=threads.get(t.id);if(previous && JSON.stringify(previous)!==JSON.stringify(t))throw new Error('REVIEW_THREADS_CHANGED_DURING_SCAN');threads.set(t.id,t);
+  }
+  cursor=page.next;
+  if(cursor) {if(cursors.has(cursor))throw new Error('REVIEW_THREADS_CURSOR_REPEATED');cursors.add(cursor);}
+ }while(cursor!==null);
+ const unresolved=[...threads.values()].filter(t=>!t.resolved);
+ return {status:'checked',total:threads.size,unresolved:unresolved.length,bugbotUnresolved:unresolved.filter(t=>/bugbot/i.test(t.author ?? '')).length};
+}

package/src/delivery/stack.ts

@@ -0,0 +1,76 @@
+import { execFileSync } from 'node:child_process';
+import { realpathSync, writeFileSync } from 'node:fs';
+import { fingerprint, git } from '../artifacts/fingerprint.ts';
+import { hash, protocol, transact } from '../runtime/protocol.ts';
+import { homePath } from '../runtime/home.ts';
+import { preparePR, openPreparedPR } from './prepare.ts';
+import type { PullRequest } from './provider.ts';
+
+export interface StackLane {key:string;cwd:string;head:string;ledgerId:string;title:string}
+export interface StackInput {repo:string;rootBase:string;owner:string;lanes:StackLane[]}
+export interface StackPlan extends StackInput {id:string;rootSha:string;entries:(StackLane & {base:string;baseSha:string;headSha:string;patchId:string})[]}
+export interface StackProvider {
+ branchHead(repo:string,branch:string):Promise<string>;
+ find(repo:string,head:string):Promise<number|null>;
+ read(repo:string,number:number):Promise<PullRequest>;
+ open(repo:string,base:string,head:string,title:string,bodyFile:string):Promise<string>;
+}
+function validBranch(branch:string):boolean {return typeof branch==='string' && /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch) && !branch.includes('..') && !branch.includes('//') && !branch.endsWith('/') && !branch.endsWith('.lock');}
+function laneMatches(pr:PullRequest,repo:string,lane:StackPlan['entries'][number]):boolean {
+ return pr.repo===repo && pr.state==='OPEN' && pr.baseRef===lane.base && pr.baseSha===lane.baseSha && pr.headSha===lane.headSha && pr.draft===false;
+}
+function patchId(cwd:string,base:string,head:string):string {
+ const diff=execFileSync('git',['-C',cwd,'diff','--no-ext-diff','--no-textconv','--binary',base,head],{encoding:'utf8',maxBuffer:64*1024*1024});
+ const result=execFileSync('git',['patch-id','--stable'],{input:diff,encoding:'utf8',maxBuffer:1024}).trim().split(/\s/)[0];
+ if(!/^[a-f0-9]{40}$/.test(result))throw new Error('STACK_EMPTY_PATCH');return result;
+}
+export async function prepareStack(input:StackInput,provider:StackProvider):Promise<StackPlan> {
+ if(!/^[\w.-]+\/[\w.-]+$/.test(input.repo) || !validBranch(input.rootBase) || !input.owner?.trim() || !Array.isArray(input.lanes) || !input.lanes.length || input.lanes.length>32)throw new Error('INVALID_STACK_PLAN');
+ if(new Set(input.lanes.map(l=>l.key)).size!==input.lanes.length || new Set(input.lanes.map(l=>l.head)).size!==input.lanes.length || input.lanes.some(l=>!validBranch(l.head) || l.head===input.rootBase || !l.key || !l.title))throw new Error('INVALID_STACK_LANES');
+ const rootSha=await provider.branchHead(input.repo,input.rootBase);
+ if(!/^[a-f0-9]{40}$/.test(rootSha))throw new Error('STACK_BASE_UNKNOWN');
+ let base=input.rootBase,baseSha=rootSha,repoId:string|undefined;const entries:StackPlan['entries']=[],worktrees=new Set<string>();
+ for(const lane of input.lanes) {
+  const cwd=realpathSync(lane.cwd),fp=fingerprint(cwd,'committed');
+  if(worktrees.has(cwd) || repoId && fp.repoId!==repoId)throw new Error('STACK_WORKTREE_IDENTITY');worktrees.add(cwd);repoId=fp.repoId;
+  if(git(cwd,['branch','--show-current'])!==lane.head)throw new Error('STACK_BRANCH_MISMATCH');
+  if(await provider.branchHead(input.repo,lane.head)!==fp.commitSha)throw new Error('REMOTE_BRANCH_NOT_VERIFIED');
+  try{git(cwd,['merge-base','--is-ancestor',baseSha,fp.commitSha]);}catch{throw new Error('STACK_TOPOLOGY_MISMATCH');}
+  const prepared=preparePR(cwd,lane.ledgerId,{repo:input.repo,base,head:lane.head,title:lane.title});
+  const ledger=protocol().ledgers[lane.ledgerId];
+  if(ledger.diffBase?.commitSha!==baseSha || ledger.verdict!=='unit-test-verified')throw new Error('STACK_PARENT_VERIFICATION_REQUIRED');
+  entries.push({...lane,cwd,base,baseSha,headSha:prepared.headSha,patchId:patchId(cwd,baseSha,fp.commitSha)});base=lane.head;baseSha=fp.commitSha;
+ }
+ const stable={repo:input.repo,rootBase:input.rootBase,owner:input.owner,lanes:entries.map(({key,cwd,head,ledgerId,title})=>({key,cwd,head,ledgerId,title})),rootSha,entries},plan={...stable,id:`stack-${hash(stable).slice(0,20)}`};
+ transact('stack-prepared',plan.id,input.owner,()=>({repo:plan.repo,rootSha,entries:entries.map(e=>({key:e.key,base:e.base,head:e.head,headSha:e.headSha,patchId:e.patchId}))}));return plan;
+}
+export async function openStack(plan:StackPlan,provider:StackProvider,approve=false):Promise<unknown> {
+ const current=await prepareStack({repo:plan.repo,rootBase:plan.rootBase,owner:plan.owner,lanes:plan.lanes},provider);
+ if(current.id!==plan.id || hash(current.entries)!==hash(plan.entries))throw new Error('STACK_PLAN_STALE');
+ if(!approve)return {plan:current,dryRun:true,mergeAuthorized:false};
+ const opened:{key:string;number?:number;url?:string;reused:boolean}[]=[];
+ for(const lane of plan.entries) {
+  // Recheck both refs immediately before each creation; stop rather than rewrite topology.
+  if(await provider.branchHead(plan.repo,lane.base)!==lane.baseSha || await provider.branchHead(plan.repo,lane.head)!==lane.headSha)throw new Error('STACK_REFS_MOVED');
+  const existing=await provider.find(plan.repo,lane.head);
+  if(existing!==null) {
+   const pr=await provider.read(plan.repo,existing);
+   if(!laneMatches(pr,plan.repo,lane))throw new Error('STACK_EXISTING_PR_MISMATCH');
+   opened.push({key:lane.key,number:existing,reused:true});continue;
+  }
+  const prepared=preparePR(lane.cwd,lane.ledgerId,{repo:plan.repo,base:lane.base,head:lane.head,title:lane.title});
+  prepared.body=`## Why\n${lane.title}\n\n## What changed\nVerified stack unit ${lane.key}.\n\n## Scope\nOnly this branch relative to ${lane.base}.\n\n## Blast Radius\nReview this unit independently; dependencies land bottom-up. No merge authority.\n\n## Verification\nHead: ${lane.headSha}\nBase: ${lane.baseSha}\nPatch ID: ${lane.patchId}\nLedger: ${lane.ledgerId}\nIndependent semantic review and current remote CI remain required.\n`;
+  const result=await openPreparedPR(lane.cwd,prepared,provider as any,true) as {url:string};
+  // A ref can move between the last check and creation. Read the new PR back, or this lane's
+  // verification would describe a commit the PR does not hold. Stop the stack and revoke the
+  // lane's ledger when that happens.
+  const created=await provider.find(plan.repo,lane.head);
+  if(created===null)throw new Error('STACK_CREATED_PR_UNREADABLE');
+  if(!laneMatches(await provider.read(plan.repo,created),plan.repo,lane)) {
+   transact('stack-verification-stale',plan.id,plan.owner,s=>{s.invalidations[lane.ledgerId]={at:new Date().toISOString(),reason:'PR_CREATED_FROM_UNVERIFIED_REFS'};return {key:lane.key,number:created};});
+   throw new Error('STACK_CREATED_PR_MISMATCH');
+  }
+  opened.push({key:lane.key,number:created,...result,reused:false});
+ }
+ transact('stack-opened',plan.id,plan.owner,()=>({opened,mergeAuthorized:false}));return {id:plan.id,opened,mergeAuthorized:false};
+}