@agilno-tech/rivet 0.1.0-alpha.0

package/src/delivery/bitbucket-review.js

@@ -0,0 +1,123 @@
+import { captureRecord, createProviderWireBody } from '../adapters/contract.js';
+import { createProviderHttpClient } from '../adapters/http.js';
+import { parseRepositoryRemote } from '../repositories/identity.js';
+import { createTrustedDeliveryExecutor } from './service.js';
+import { reviewRequestContent } from './review-request.js';
+import { digest, ensure, exact, factsDigest, hash, plain, sha, timestamp, validateCandidate } from './contract.js';
+
+const API='https://api.bitbucket.org/2.0';
+const STATES=['OPEN','MERGED','DECLINED','SUPERSEDED'];
+const UUID=/^\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\}$/i;
+// Bitbucket accepts refs rather than an expected commit condition. Creation is
+// confirmed only after exact readback and stable repository/branch observations.
+export function createBitbucketReviewExecutor(inputConfig) {
+  const input=captureRecord(inputConfig,new Set(['repository','transport','headers','clock','timeoutMs']),['repository','transport'],'invalid-config');
+  const supplied=plain(input.repository),repository=parseRepositoryRemote(supplied.url);
+  ensure(repository.provider==='bitbucket'&&hash(repository)===hash(supplied));
+  const clock=input.clock??(()=>new Date().toISOString());ensure(typeof clock==='function');
+  const http=createProviderHttpClient({provider:'bitbucket',baseUrl:API,transport:input.transport,allowEncodedSlash:true,
+    ...(input.headers===undefined?{}:{headers:input.headers}),...(input.timeoutMs===undefined?{}:{timeoutMs:input.timeoutMs})});
+  const root=`/repositories/${repository.fullName}`,listPath=root+'/pullrequests';
+  const get=async path=>(await http.request({method:'GET',path:root+path})).data;
+  function number(value){ensure(Number.isSafeInteger(value)&&value>0,'invalid-provider-evidence');return value;}
+  function target(value){validateCandidate(value);ensure(hash(value.repository)===hash(repository),'provider-mismatch');}
+  function identity(value,embedded=false){
+    ensure(typeof value?.uuid==='string'&&UUID.test(value.uuid)&&value.full_name===repository.fullName&&value.links?.html?.href===repository.url,'changed-facts');
+    let workspace=null;
+    if(!embedded||value.workspace!==undefined){ensure(typeof value.workspace?.uuid==='string'&&UUID.test(value.workspace.uuid)&&value.workspace.slug===repository.namespace,'changed-facts');workspace={uuid:value.workspace.uuid,slug:value.workspace.slug};}
+    return {uuid:value.uuid,fullName:repository.fullName,url:repository.url,workspace};
+  }
+  async function branches(candidate){
+    const project=identity(await get(''));
+    const branch=async name=>{
+      let result;try{result=await get(`/refs/branches/${encodeURIComponent(name)}`);}catch(error){
+        if(error?.status===404){const failure=new Error('Publish the verified source branch and ensure the target branch exists before requesting review.');failure.code='ERR_DELIVERY_BRANCH_NOT_PUBLISHED';failure.safeMessage=failure.message;throw failure;}throw error;
+      }
+      ensure(result?.name===name,'changed-facts');return sha(result.target?.hash);
+    };
+    const headSha=await branch(candidate.sourceBranch),baseSha=await branch(candidate.targetBranch);
+    ensure(headSha===candidate.headSha,'changed-facts');return {project,headSha,baseSha};
+  }
+  function rawBody(value){
+    const fields=[value.description,value.summary?.raw,value.rendered?.description?.raw].filter(field=>field!==undefined);
+    ensure(fields.length>0&&fields.every(field=>typeof field==='string'&&field===fields[0]),'invalid-provider-evidence');
+    return fields[0];
+  }
+  function review(value,candidate,before){
+    const id=number(value?.id);
+    ensure(STATES.includes(value.state)&&typeof value.draft==='boolean'&&value.links?.html?.href===`${repository.url}/pull-requests/${id}`,'changed-facts');
+    for(const [side,name,commit] of [['source',candidate.sourceBranch,candidate.headSha],['destination',candidate.targetBranch,before.baseSha]]){
+      const part=value[side],repo=identity(part?.repository,true);
+      ensure(repo.uuid===before.project.uuid&&(repo.workspace===null||hash(repo.workspace)===hash(before.project.workspace))
+        &&part.branch?.name===name&&part.commit?.hash===commit,'changed-facts');
+    }
+    ensure(typeof value.title==='string','changed-facts');const body=rawBody(value);
+    return plain({number:id,state:value.state==='OPEN'?'open':value.state==='MERGED'?'merged':'closed',draft:value.draft,url:value.links.html.href,
+      headSha:candidate.headSha,baseSha:before.baseSha,title:value.title,body});
+  }
+  // JSON next links are API input: pin all selectors and reject hidden partial
+  // responses. Bounds and duplicate IDs apply across all four state queries.
+  async function listed(candidate){
+    const result=[],ids=new Set(),visited=new Set();let pages=0;
+    const q=`source.branch.name=${JSON.stringify(candidate.sourceBranch)} AND destination.branch.name=${JSON.stringify(candidate.targetBranch)}`;
+    for(const state of STATES){
+      let declaredSize=null,received=0;
+      let next=new URL(API+listPath);next.search=new URLSearchParams({q,state,pagelen:'100'}).toString();
+      while(next){
+        ensure(++pages<=20&&next.origin==='https://api.bitbucket.org'&&next.pathname==='/2.0'+listPath&&!next.username&&!next.password&&!next.hash,'invalid-pagination');
+        const params=next.searchParams,keys=[...params.keys()];
+        ensure(new Set(keys).size===keys.length&&keys.every(key=>['q','state','pagelen','page'].includes(key))
+          &&params.get('q')===q&&params.get('state')===state&&params.get('pagelen')==='100'
+          &&(!params.has('page')||/^[1-9][0-9]{0,5}$/.test(params.get('page'))),'invalid-pagination');
+        const canonical=new URL(next);canonical.searchParams.sort();ensure(!visited.has(canonical.href),'invalid-pagination');visited.add(canonical.href);
+        const requestedPage=Number(params.get('page')??'1');
+        const page=(await http.request({method:'GET',path:next.pathname.slice('/2.0'.length)+next.search})).data;
+        ensure(Array.isArray(page?.values)&&page.values.length<=100,'invalid-pagination');
+        if(page.page!==undefined)ensure(page.page===requestedPage,'invalid-pagination');
+        if(page.pagelen!==undefined)ensure(page.pagelen===100,'invalid-pagination');
+        if(page.size!==undefined){ensure(Number.isSafeInteger(page.size)&&page.size>=0&&page.size<=1000&&(declaredSize===null||declaredSize===page.size),'invalid-pagination');declaredSize=page.size;}
+        received+=page.values.length;ensure(declaredSize===null||received<=declaredSize,'invalid-pagination');
+        for(const row of page.values){const id=number(row?.id);ensure(!ids.has(id)&&row.state===state,'invalid-pagination');ids.add(id);result.push(row);ensure(result.length<=1000,'invalid-pagination');}
+        if(page.next===undefined||page.next===null){ensure(declaredSize===null||received===declaredSize,'invalid-pagination');break;}
+        ensure(page.values.length>0&&typeof page.next==='string'&&page.next.length<=8192,'invalid-pagination');
+        try{next=new URL(page.next);}catch{ensure(false,'invalid-pagination');}
+        ensure(next.searchParams.get('page')===String(requestedPage+1),'invalid-pagination');
+      }
+    }
+    return result;
+  }
+  function facts(candidate,before,existing){
+    const unknown={headSha:candidate.headSha,policy:'unknown',satisfied:null,evidenceDigest:hash({before,existing})};
+    return plain({repositoryUrl:repository.url,sourceBranch:candidate.sourceBranch,targetBranch:candidate.targetBranch,headSha:candidate.headSha,baseSha:before.baseSha,
+      review:existing?{number:existing.number,state:existing.state,url:existing.url,headSha:candidate.headSha}:null,checks:unknown,reviews:unknown,observedAt:timestamp(clock())});
+  }
+  async function observe(candidate){
+    target(candidate);const before=await branches(candidate),rows=await listed(candidate);ensure(rows.length<=1,'ambiguous-review');let existing=null;
+    if(rows.length){const selected=number(rows[0].id);existing=review(await get(`/pullrequests/${selected}`),candidate,before);ensure(existing.number===selected&&(candidate.reviewNumber===null||candidate.reviewNumber===selected),'changed-facts');}
+    else ensure(candidate.reviewNumber===null,'changed-facts');
+    ensure(hash(await branches(candidate))===hash(before),'changed-facts');return facts(candidate,before,existing);
+  }
+  function operation(value){const op=plain(value);target(op.candidate);digest(op.digest);digest(op.factsDigest);ensure(op.action==='review-request'&&op.candidate.reviewNumber===null,'unsupported-action');reviewRequestContent(op);return op;}
+  function verified(value,op,before){const result=review(value,op.candidate,before),content=reviewRequestContent(op);ensure(!result.draft&&value.close_source_branch===false&&result.title===content.title&&result.body===content.body,'unverified-effect');return result;}
+  function receipt(op,result){return plain({status:'succeeded',operationDigest:op.digest,headSha:op.candidate.headSha,evidenceDigest:hash(result),resourceUrl:result.url,commitSha:null});}
+  async function marked(op,before){
+    const marker=`<!-- rivet-review-operation:${op.digest} -->`,rows=await listed(op.candidate);
+    const matches=rows.filter(row=>rawBody(row).includes(marker));ensure(matches.length===1,'ambiguous-review');
+    const selected=number(matches[0].id),result=verified(await get(`/pullrequests/${selected}`),op,before);ensure(result.number===selected,'changed-facts');return result;
+  }
+  async function dispatch(value,context){
+    const op=operation(value),limits=plain(context);exact(limits,['deadline']);const deadline=Date.parse(timestamp(limits.deadline));
+    const timely=()=>ensure(Date.parse(timestamp(clock()))<deadline,'dispatch-expired');timely();
+    const observed=await observe(op.candidate);ensure(observed.review===null&&factsDigest(observed)===op.factsDigest,'changed-facts');
+    const content=reviewRequestContent(op),wireBody=createProviderWireBody({provider:'bitbucket',action:'review-request',resourceId:repository.fullName,expectedState:'absent',expectedVersion:op.candidate.headSha,idempotencyKey:op.digest,
+      payload:{title:content.title,description:content.body,source:{branch:{name:op.candidate.sourceBranch}},destination:{branch:{name:op.candidate.targetBranch}},draft:false,close_source_branch:false}});
+    timely();const controller=new AbortController(),remaining=deadline-Date.parse(timestamp(clock()));ensure(remaining>0,'dispatch-expired');const timer=setTimeout(()=>controller.abort(),remaining);
+    let response;try{response=await http.request({method:'POST',path:listPath,wireBody,signal:controller.signal});}finally{clearTimeout(timer);}
+    ensure(response.status===201,'unverified-effect');const after=await branches(op.candidate);
+    ensure(hash({before:after,existing:null})===observed.checks.evidenceDigest,'changed-facts');
+    const sent=verified(response.data,op,after);ensure(sent.state==='open','unverified-effect');
+    const result=await marked(op,after);ensure(hash(sent)===hash(result)&&hash(await branches(op.candidate))===hash(after),'changed-facts');return receipt(op,result);
+  }
+  async function reconcile(value){try{const op=operation(value),before=await branches(op.candidate);ensure(factsDigest(facts(op.candidate,before,null))===op.factsDigest,'changed-facts');const result=await marked(op,before);ensure(hash(await branches(op.candidate))===hash(before),'changed-facts');return {status:'succeeded',receipt:receipt(op,result)};}catch{return {status:'unknown'};}}
+  return createTrustedDeliveryExecutor({provider:'bitbucket',capabilities:[{action:'review-request',conditionalHead:false,verifiesCreatedReview:true,reconcile:true}],observe,dispatch,reconcile});
+}

package/src/delivery/branch-publication.js

@@ -0,0 +1,23 @@
+import { createTrustedDeliveryExecutor } from './service.js';
+import { ensure, exact, hash, sha, factsDigest } from './contract.js';
+import { publicationRef } from './publication-transport.js';
+export function publicationPayload(target) {return {destinationUrl:target.repository.url+'.git',ref:publicationRef(target.sourceBranch),headSha:target.headSha};}
+export function createBranchPublicationExecutor({repository,transport}) {
+  ensure(transport&&typeof transport.readRefs==='function'&&typeof transport.push==='function');
+  const validate=op=>{ensure(op.action==='branch-publish'&&hash(op.candidate.repository)===hash(repository));ensure(hash(op.payload)===hash(publicationPayload(op.candidate)),'invalid-publication');};
+  const inspect=async target=>{
+    ensure(hash(target.repository)===hash(repository));const refs=await transport.readRefs(target);exact(refs,['sourceSha','baseSha']);sha(refs.baseSha);if(refs.sourceSha!==null)sha(refs.sourceSha);return refs;
+  };
+  const receipt=(op,refs)=>({status:'succeeded',operationDigest:op.digest,headSha:op.candidate.headSha,commitSha:op.candidate.headSha,resourceUrl:repository.url,evidenceDigest:hash({assurance:'publication-requirement-satisfied',publication:op.payload,remoteSha:refs.sourceSha})});
+  async function observe(target) {
+      const refs=await inspect(target);const policy={headSha:target.headSha,policy:'unknown',satisfied:null,evidenceDigest:hash({publication:refs})};
+      return {repositoryUrl:repository.url,sourceBranch:target.sourceBranch,targetBranch:target.targetBranch,headSha:target.headSha,baseSha:refs.baseSha,review:null,checks:policy,reviews:policy,observedAt:new Date().toISOString(),publication:{destinationUrl:repository.url+'.git',ref:publicationRef(target.sourceBranch),remoteSha:refs.sourceSha}};
+    }
+  return createTrustedDeliveryExecutor({provider:repository.provider,capabilities:[{action:'branch-publish',conditionalHead:true,reconcile:true}],observe,
+    async dispatch(op,context) {
+      validate(op);const current=await observe(op.candidate);ensure(current.publication.remoteSha===null,'branch-exists');ensure(factsDigest(current)===op.factsDigest,'changed-facts');
+      await transport.push(op.candidate,context);const refs=await inspect(op.candidate);ensure(refs.sourceSha===op.candidate.headSha,'publication-outcome-uncertain');return receipt(op,refs);
+    },
+    async reconcile(op) {validate(op);const refs=await inspect(op.candidate);return refs.sourceSha===op.candidate.headSha?{status:'succeeded',receipt:receipt(op,refs)}:{status:'unknown'};},
+  });
+}

package/src/delivery/contract.js

@@ -0,0 +1,379 @@
+import { createHash } from 'node:crypto';
+import { containsSecretMaterial } from '../clients/contract.js';
+import { parseRepositoryRemote } from '../repositories/identity.js';
+
+export const ACTIONS = Object.freeze(['branch-publish', 'review-request', 'review-update', 'merge', 'deploy', 'tracker-update', 'tracker-transition']);
+export const STAGES = Object.freeze([
+  'locally-verified',
+  'branch-published',
+  'review-requested',
+  'checks-passed',
+  'merge-approved',
+  'merged',
+  'deployed',
+  'tracker-updated',
+  'tracker-status-confirmed',
+]);
+export class DeliveryError extends Error {
+  constructor(reason = 'invalid-input') {
+    super(`Delivery operation failed: ${reason}.`);
+    this.name = 'DeliveryError';
+    this.code = `ERR_DELIVERY_${reason.replaceAll('-', '_').toUpperCase()}`;
+    this.safeMessage = this.message;
+  }
+}
+export function fail(reason) {
+  throw new DeliveryError(reason);
+}
+export function ensure(value, reason = 'invalid-input') {
+  if (!value) fail(reason);
+}
+export function plain(input) {
+  let nodes = 0;
+  function copy(value, depth) {
+    ensure(++nodes <= 10000 && depth <= 20);
+    if (value === null || typeof value === 'boolean') return value;
+    if (typeof value === 'string') {
+      ensure(value.length <= 65536 && !containsSecretMaterial(value));
+      return value;
+    }
+    if (typeof value === 'number') {
+      ensure(Number.isSafeInteger(value));
+      return value;
+    }
+    ensure(value && typeof value === 'object');
+    const array = Array.isArray(value);
+    ensure(
+      Object.getPrototypeOf(value) === (array ? Array.prototype : Object.prototype) ||
+        (!array && Object.getPrototypeOf(value) === null)
+    );
+    const out = array ? [] : {};
+    for (const key of Reflect.ownKeys(value)) {
+      if (array && key === 'length') continue;
+      ensure(typeof key === 'string' && key !== '__proto__');
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      ensure(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+      if (array) ensure(/^(?:0|[1-9][0-9]*)$/.test(key) && Number(key) < value.length);
+      else ensure(!containsSecretMaterial(`${key}: sensitive-value`));
+      out[key] = copy(descriptor.value, depth + 1);
+    }
+    if (array) ensure(out.length === value.length && Object.keys(out).length === value.length);
+    return Object.freeze(out);
+  }
+  const result = copy(input, 0);
+  ensure(Buffer.byteLength(JSON.stringify(result)) <= 262144);
+  return result;
+}
+export function exact(value, keys, optional = []) {
+  ensure(value && typeof value === 'object' && !Array.isArray(value));
+  ensure(
+    Object.keys(value).every((key) => keys.includes(key) || optional.includes(key)) &&
+      keys.every((key) => Object.hasOwn(value, key))
+  );
+  return value;
+}
+export function id(value) {
+  ensure(typeof value === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(value));
+  return value;
+}
+export function sha(value) {
+  ensure(typeof value === 'string' && /^[a-f0-9]{40}$/.test(value));
+  return value;
+}
+export function digest(value) {
+  ensure(typeof value === 'string' && /^[a-f0-9]{64}$/.test(value));
+  return value;
+}
+export function timestamp(value) {
+  ensure(
+    typeof value === 'string' &&
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) &&
+      Number.isFinite(Date.parse(value)) &&
+      new Date(value).toISOString() === value
+  );
+  return value;
+}
+export function ref(value) {
+  ensure(
+    typeof value === 'string' &&
+      /^[A-Za-z0-9_][A-Za-z0-9._/-]{0,254}$/.test(value) &&
+      !value.includes('..') &&
+      !value.includes('//')
+  );
+  return value;
+}
+export function hash(value) {
+  const canonical = (item) =>
+    item === null || typeof item !== 'object'
+      ? JSON.stringify(item)
+      : Array.isArray(item)
+        ? `[${item.map(canonical).join(',')}]`
+        : `{${Object.keys(item)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(item[key])}`)
+            .join(',')}}`;
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}
+export function candidate(input) {
+  const value = plain(input);
+  exact(
+    value,
+    ['runId', 'repository', 'sourceBranch', 'targetBranch', 'localVerification'],
+    ['reviewNumber']
+  );
+  id(value.runId);
+  ref(value.sourceBranch);
+  ref(value.targetBranch);
+  const repository = parseRepositoryRemote(value.repository.url);
+  ensure(hash(repository) === hash(value.repository));
+  const proof = exact(value.localVerification, [
+    'runId',
+    'headSha',
+    'evidenceDigest',
+    'verifiedAt',
+    'status',
+  ]);
+  ensure(proof.runId === value.runId && proof.status === 'passed');
+  sha(proof.headSha);
+  digest(proof.evidenceDigest);
+  timestamp(proof.verifiedAt);
+  ensure(
+    value.reviewNumber === undefined || (Number.isSafeInteger(value.reviewNumber) && value.reviewNumber > 0)
+  );
+  return plain({ ...value, headSha: proof.headSha, reviewNumber: value.reviewNumber ?? null });
+}
+export function validateCandidate(value) {
+  const { headSha, reviewNumber, ...input } = value;
+  const result = candidate({ ...input, ...(reviewNumber === null ? {} : { reviewNumber }) });
+  ensure(result.headSha === headSha);
+  return value;
+}
+export function observation(input, target) {
+  const value = plain(input);
+  exact(value, [
+    'repositoryUrl',
+    'sourceBranch',
+    'targetBranch',
+    'headSha',
+    'baseSha',
+    'review',
+    'checks',
+    'reviews',
+    'observedAt',
+  ], ['publication']);
+  if (value.publication !== undefined) {
+    const p = exact(value.publication, ['destinationUrl', 'ref', 'remoteSha']);
+    ensure(p.destinationUrl === target.repository.url + '.git' && p.ref === `refs/heads/${target.sourceBranch}`, 'changed-facts');
+    ensure(p.remoteSha === null || sha(p.remoteSha), 'changed-facts');
+  }
+  timestamp(value.observedAt);
+  sha(value.baseSha);
+  ensure(
+    value.repositoryUrl === target.repository.url &&
+      value.sourceBranch === target.sourceBranch &&
+      value.targetBranch === target.targetBranch &&
+      value.headSha === target.headSha,
+    'changed-facts'
+  );
+  if (value.review !== null) {
+    const review = exact(value.review, ['number', 'state', 'url', 'headSha']);
+    ensure(
+      Number.isSafeInteger(review.number) &&
+        review.number > 0 &&
+        (target.reviewNumber === null || review.number === target.reviewNumber)
+    );
+    ensure(
+      ['open', 'closed', 'merged'].includes(review.state) && review.headSha === target.headSha,
+      'changed-facts'
+    );
+    const segment = { github: 'pull', bitbucket: 'pull-requests', gitlab: '-/merge_requests' }[
+      target.repository.provider
+    ];
+    ensure(review.url === `${target.repository.url}/${segment}/${review.number}`);
+  }
+  for (const key of ['checks', 'reviews']) {
+    const policy = exact(value[key], ['headSha', 'policy', 'satisfied', 'evidenceDigest']);
+    ensure(policy.headSha === target.headSha, 'changed-facts');
+    digest(policy.evidenceDigest);
+    ensure(
+      policy.policy === 'unknown'
+        ? policy.satisfied === null
+        : policy.policy === 'known' && typeof policy.satisfied === 'boolean'
+    );
+  }
+  return value;
+}
+export function ready(value) {
+  return (
+    value?.review?.state === 'open' &&
+    ['checks', 'reviews'].every((key) => value[key].policy === 'known' && value[key].satisfied === true)
+  );
+}
+export function factsDigest(value) {
+  const { observedAt, ...facts } = value;
+  return hash(facts);
+}
+export function validateReceipt(input, operation) {
+  const value = plain(input);
+  exact(value, ['status', 'operationDigest', 'headSha', 'evidenceDigest', 'resourceUrl', 'commitSha']);
+  ensure(
+    value.status === 'succeeded' &&
+      value.operationDigest === operation.digest &&
+      value.headSha === operation.candidate.headSha,
+    'invalid-receipt'
+  );
+  digest(value.evidenceDigest);
+  let url;
+  try {
+    url = new URL(value.resourceUrl);
+  } catch {
+    fail('invalid-receipt');
+  }
+  ensure(
+    url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash,
+    'invalid-receipt'
+  );
+  ensure(value.commitSha === null || sha(value.commitSha));
+  if (operation.action === 'merge') sha(value.commitSha);
+  if (operation.action === 'branch-publish') ensure(value.commitSha === operation.candidate.headSha && value.resourceUrl === operation.candidate.repository.url, 'invalid-receipt');
+  return value;
+}
+export function mergeReceiptFor(operations, action) {
+  if (!['deploy', 'tracker-update', 'tracker-transition'].includes(action)) return null;
+  const merge = operations.find(
+    (operation) => operation.action === 'merge' && operation.state === 'succeeded'
+  );
+  ensure(merge?.receipt?.commitSha, 'missing-merge-receipt');
+  return merge.receipt;
+}
+
+function publicationPayload(value, target) {
+  exact(value, ['destinationUrl', 'ref', 'headSha']);
+  ensure(value.destinationUrl === target.repository.url + '.git' && value.ref === `refs/heads/${target.sourceBranch}` && value.headSha === target.headSha, 'invalid-publication');
+}
+
+export function validateRecord(input) {
+  const value = plain(input);
+  exact(value, [
+    'schemaVersion',
+    'stage',
+    'candidate',
+    'observation',
+    'proposal',
+    'operations',
+    'usedApprovalIds',
+    'createdAt',
+    'updatedAt',
+  ]);
+  ensure(value.schemaVersion === 1 && STAGES.includes(value.stage));
+  validateCandidate(value.candidate);
+  timestamp(value.createdAt);
+  timestamp(value.updatedAt);
+  ensure(value.updatedAt >= value.createdAt);
+  if (value.observation !== null) observation(value.observation, value.candidate);
+  ensure(
+    Array.isArray(value.operations) &&
+      value.operations.length <= 64 &&
+      Array.isArray(value.usedApprovalIds) &&
+      value.usedApprovalIds.length <= 64 &&
+      new Set(value.usedApprovalIds).size === value.usedApprovalIds.length
+  );
+  for (const operation of value.operations) {
+    exact(operation, [
+      'digest',
+      'action',
+      'payload',
+      'candidate',
+      'factsDigest',
+      'mergeReceipt',
+      'approvalId',
+      'dispatchedAt',
+      'state',
+      'receipt',
+    ]);
+    ensure(
+      hash(operation.mergeReceipt) ===
+        hash(
+          mergeReceiptFor(value.operations.slice(0, value.operations.indexOf(operation)), operation.action)
+        ),
+      'merge-receipt-mismatch'
+    );
+    if (operation.action === 'branch-publish') publicationPayload(operation.payload, value.candidate);
+    digest(operation.digest);
+    digest(operation.factsDigest);
+    id(operation.approvalId);
+    timestamp(operation.dispatchedAt);
+    ensure(
+      ACTIONS.includes(operation.action) &&
+        ['dispatching', 'indeterminate', 'succeeded', 'not-applied'].includes(operation.state)
+    );
+    ensure(
+      hash(operation.candidate) === hash(value.candidate) &&
+        value.usedApprovalIds.includes(operation.approvalId)
+    );
+    if (operation.receipt !== null) {
+      ensure(operation.state === 'succeeded');
+      validateReceipt(operation.receipt, operation);
+    } else ensure(operation.state !== 'succeeded');
+  }
+  if (value.proposal !== null) {
+    const p = exact(value.proposal, [
+      'digest',
+      'action',
+      'payload',
+      'expiresAt',
+      'factsDigest',
+      'nonce',
+      'resource',
+      'approvalResource',
+      'providerId',
+      'mergeReceipt',
+    ]);
+    ensure(
+      hash(p.mergeReceipt) === hash(mergeReceiptFor(value.operations, p.action)),
+      'merge-receipt-mismatch'
+    );
+    if (p.action === 'branch-publish') publicationPayload(p.payload, value.candidate);
+    digest(p.digest);
+    digest(p.factsDigest);
+    timestamp(p.expiresAt);
+    id(p.providerId);
+    ensure(ACTIONS.includes(p.action) && typeof p.nonce === 'string');
+    const body = {
+      candidate: value.candidate,
+      action: p.action,
+      payload: p.payload,
+      expiresAt: p.expiresAt,
+      factsDigest: p.factsDigest,
+      nonce: p.nonce,
+      providerId: p.providerId,
+      mergeReceipt: p.mergeReceipt,
+    };
+    ensure(
+      hash(body) === p.digest &&
+        p.resource === `delivery:${p.digest}` &&
+        p.approvalResource === `${p.providerId}:${p.action}:${p.resource}`
+    );
+  }
+  const success = (action) => value.operations.some((op) => op.action === action && op.state === 'succeeded');
+  if (['merged', 'deployed', 'tracker-updated', 'tracker-status-confirmed'].includes(value.stage)) ensure(success('merge'));
+  if (value.stage === 'branch-published') ensure(success('branch-publish'));
+  if (value.stage === 'deployed') ensure(success('deploy'));
+  if (value.stage === 'tracker-status-confirmed') ensure(success('tracker-transition'));
+  if (value.stage === 'tracker-updated') ensure(success('tracker-update'));
+  if (value.stage === 'merge-approved')
+    ensure(
+      value.operations.some(
+        (op) => op.action === 'merge' && ['dispatching', 'indeterminate', 'not-applied'].includes(op.state)
+      )
+    );
+  if (value.stage === 'review-requested')
+    ensure((value.observation?.review !== null && value.observation !== null) || success('review-request'));
+  ensure(
+    new Set(value.operations.map((op) => op.digest)).size === value.operations.length &&
+      new Set(value.operations.map((op) => op.approvalId)).size === value.operations.length &&
+      value.usedApprovalIds.length === value.operations.length
+  );
+  if (value.stage === 'checks-passed') ensure(ready(value.observation));
+  return value;
+}

package/src/delivery/github-deployment.js

@@ -0,0 +1,132 @@
+import { createProviderHttpClient } from '../adapters/http.js';
+import { captureRecord, createProviderWireBody } from '../adapters/contract.js';
+import { parseRepositoryRemote } from '../repositories/identity.js';
+import { createTrustedDeliveryExecutor } from './service.js';
+import { digest, ensure, exact, factsDigest, hash, id, plain, sha, timestamp, validateCandidate, validateReceipt } from './contract.js';
+
+export function deploymentPayload(config) {
+  const value = plain(config);
+  exact(value, ['providerId', 'workflow', 'environment', 'productionEnvironment']);
+  id(value.providerId);
+  ensure(typeof value.workflow === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}\.ya?ml$/.test(value.workflow));
+  ensure(typeof value.environment === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(value.environment));
+  ensure(typeof value.productionEnvironment === 'boolean');
+  return plain({ workflow: value.workflow, environment: value.environment, productionEnvironment: value.productionEnvironment });
+}
+
+// The configured project workflow is trusted to perform deployment and verify its
+// result. GitHub run success proves that workflow's result, not generic app health.
+export function createGithubDeploymentExecutor(inputConfig) {
+  const input = captureRecord(inputConfig,
+    new Set(['repository', 'deployment', 'mergeReceipt', 'transport', 'headers', 'clock', 'timeoutMs']),
+    ['repository', 'deployment', 'mergeReceipt', 'transport'], 'invalid-config');
+  const supplied = plain(input.repository), repository = parseRepositoryRemote(supplied.url);
+  ensure(repository.provider === 'github' && hash(repository) === hash(supplied));
+  const payload = deploymentPayload(input.deployment), merged = plain(input.mergeReceipt);
+  validateReceipt(merged, {action: 'merge', digest: digest(merged.operationDigest), candidate: {headSha: sha(merged.headSha)}});
+  const prPrefix = `${repository.url}/pull/`;
+  ensure(merged.resourceUrl.startsWith(prPrefix));
+  const pullNumber = Number(merged.resourceUrl.slice(prPrefix.length));
+  ensure(Number.isSafeInteger(pullNumber) && pullNumber > 0 && pullNumber <= 1_000_000_000
+    && merged.resourceUrl === `${prPrefix}${pullNumber}`);
+  const clock = input.clock ?? (() => new Date().toISOString());
+  ensure(typeof clock === 'function');
+  const http = createProviderHttpClient({provider: 'github', baseUrl: 'https://api.github.com', transport: input.transport,
+    ...(input.headers === undefined ? {} : {headers: input.headers}),
+    ...(input.timeoutMs === undefined ? {} : {timeoutMs: input.timeoutMs})});
+  const root = `/repos/${repository.fullName}`;
+  const get = async path => (await http.request({method: 'GET', path: root + path})).data;
+  const pages = path => http.paginate({path: root + path, identityKey: 'id'});
+  function target(candidate) {
+    validateCandidate(candidate);
+    ensure(hash(candidate.repository) === hash(repository) && candidate.headSha === merged.headSha, 'changed-facts');
+    ensure(candidate.reviewNumber === null || candidate.reviewNumber === pullNumber, 'changed-facts');
+  }
+  async function workflow() {
+    const value = await get(`/actions/workflows/${encodeURIComponent(payload.workflow)}`);
+    ensure(Number.isSafeInteger(value?.id) && value.id > 0 && value.state === 'active'
+      && value.path === `.github/workflows/${payload.workflow}`, 'changed-facts');
+    const file = await get(`/contents/.github/workflows/${encodeURIComponent(payload.workflow)}?ref=${merged.commitSha}`);
+    ensure(file?.type === 'file' && file.path === value.path, 'changed-facts');
+    return {id: value.id, path: value.path, blobSha: sha(file.sha), state: value.state};
+  }
+  async function observe(candidate) {
+    target(candidate);
+    const pull = await get(`/pulls/${pullNumber}`);
+    ensure(pull?.number === pullNumber && pull.state === 'closed' && pull.merged === true
+      && pull.merge_commit_sha === merged.commitSha && pull.html_url === merged.resourceUrl
+      && pull.head?.sha === candidate.headSha && pull.head?.ref === candidate.sourceBranch
+      && pull.head?.repo?.full_name === repository.fullName && pull.base?.ref === candidate.targetBranch
+      && pull.base?.repo?.full_name === repository.fullName, 'changed-facts');
+    const configured = await workflow();
+    const evidence = hash({workflow: configured, payload, mergeReceipt: merged});
+    return plain({repositoryUrl: repository.url, sourceBranch: candidate.sourceBranch, targetBranch: candidate.targetBranch,
+      headSha: candidate.headSha, baseSha: sha(pull.base.sha),
+      review: {number: pullNumber, state: 'merged', url: merged.resourceUrl, headSha: candidate.headSha},
+      checks: {headSha: candidate.headSha, policy: 'unknown', satisfied: null, evidenceDigest: evidence},
+      reviews: {headSha: candidate.headSha, policy: 'unknown', satisfied: null, evidenceDigest: evidence},
+      observedAt: timestamp(clock())});
+  }
+  function operation(input) {
+    const op = plain(input);
+    target(op.candidate);
+    digest(op.digest);
+    ensure(op.action === 'deploy' && hash(op.payload) === hash(payload) && hash(op.mergeReceipt) === hash(merged), 'changed-facts');
+    return op;
+  }
+  async function reconcile(input) {
+    try {
+      const op = operation(input), configured = await workflow();
+      const matches = (await pages(`/deployments?sha=${merged.commitSha}&task=rivet-deploy&environment=${encodeURIComponent(payload.environment)}&per_page=100`))
+        .filter(item => item?.payload?.rivetOperation === op.digest);
+      ensure(matches.length === 1, 'unverified-effect');
+      const deployment = matches[0];
+      ensure(Number.isSafeInteger(deployment.id) && deployment.id > 0 && deployment.sha === merged.commitSha
+        && deployment.ref === merged.commitSha && deployment.task === 'rivet-deploy'
+        && deployment.environment === payload.environment && deployment.production_environment === payload.productionEnvironment
+        && deployment.transient_environment === false && deployment.repository_url === `https://api.github.com${root}`
+        && deployment.payload.workflow === payload.workflow, 'unverified-effect');
+      exact(deployment.payload, ['rivetOperation', 'workflow']);
+      const statuses = await pages(`/deployments/${deployment.id}/statuses?per_page=100`);
+      ensure(statuses.length > 0 && statuses.every(item => Number.isSafeInteger(item.id) && item.id > 0), 'unverified-effect');
+      const latest = statuses.reduce((a,b) => a.id > b.id ? a : b);
+      ensure(latest.state === 'success' && latest.environment === payload.environment, 'unverified-effect');
+      const runPrefix = `${repository.url}/actions/runs/`, runId = Number(String(latest.log_url).slice(runPrefix.length));
+      ensure(Number.isSafeInteger(runId) && runId > 0 && latest.log_url === `${runPrefix}${runId}`, 'unverified-effect');
+      const run = await get(`/actions/runs/${runId}`);
+      ensure(run?.id === runId && run.status === 'completed' && run.conclusion === 'success'
+        && run.head_sha === merged.commitSha && run.workflow_id === configured.id && run.event === 'deployment'
+        && run.repository?.full_name === repository.fullName && run.display_title === `rivet-deploy:${op.digest}`
+        && run.html_url === latest.log_url, 'unverified-effect');
+      return {status: 'succeeded', receipt: plain({status: 'succeeded', operationDigest: op.digest,
+        headSha: op.candidate.headSha, commitSha: merged.commitSha, resourceUrl: run.html_url,
+        evidenceDigest: hash({deployment, latest, run, workflow: configured})})};
+    } catch {
+      return {status: 'unknown'};
+    }
+  }
+  async function dispatch(input, context) {
+    const op = operation(input), ctx = plain(context);
+    exact(ctx, ['deadline']);
+    const deadline = Date.parse(timestamp(ctx.deadline));
+    const timely = () => ensure(Date.parse(timestamp(clock())) < deadline, 'dispatch-expired');
+    timely();
+    ensure(factsDigest(await observe(op.candidate)) === op.factsDigest, 'changed-facts');
+    const wireBody = createProviderWireBody({provider: 'github', action: 'deploy', resourceId: repository.fullName,
+      expectedState: 'merged', expectedVersion: merged.commitSha, idempotencyKey: op.digest,
+      payload: {ref: merged.commitSha, auto_merge: false, task: 'rivet-deploy', environment: payload.environment,
+        production_environment: payload.productionEnvironment, transient_environment: false,
+        payload: {rivetOperation: op.digest, workflow: payload.workflow}}});
+    timely();
+    const controller = new AbortController(), remaining = deadline - Date.parse(timestamp(clock()));
+    ensure(remaining > 0, 'dispatch-expired');
+    const timer = setTimeout(() => controller.abort(), remaining);
+    try {
+      await http.request({method: 'POST', path: `${root}/deployments`, wireBody, signal: controller.signal});
+    } finally { clearTimeout(timer); }
+    const result = await reconcile(op);
+    ensure(result.status === 'succeeded', 'unverified-effect');
+    return result.receipt;
+  }
+  return createTrustedDeliveryExecutor({provider:'github',capabilities:[{action:'deploy',conditionalHead:true,reconcile:true}],observe,dispatch,reconcile});
+}