@agilno-tech/rivet 0.1.0-alpha.0

package/src/delivery/tracker-transition.js

@@ -0,0 +1,158 @@
+import { captureRecord, createProviderReadBody, createProviderWireBody } from '../adapters/contract.js';
+import { createProviderHttpClient } from '../adapters/http.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';
+
+const KEY = /^[A-Z][A-Z0-9]{0,31}-[1-9][0-9]{0,15}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const NUMBER = /^[1-9][0-9]{0,19}$/;
+const ISSUE_QUERY = 'query RivetTrackerStatus($id: String!) { issue(id: $id) { id identifier url updatedAt team { id key } state { id name type team { id key } } } }';
+const STATES_QUERY = 'query RivetTrackerStates($filter: WorkflowStateFilter, $cursor: String) { workflowStates(first: 100, after: $cursor, filter: $filter) { nodes { id name type team { id key } } pageInfo { hasNextPage endCursor } } }';
+function label(value) { ensure(typeof value === 'string' && value.length >= 1 && value.length <= 200 && value.trim() === value && !/[\u0000-\u001f\u007f]/.test(value), 'invalid-provider-evidence'); return value; }
+function revision(value) { ensure(typeof value === 'string' && value.length <= 64 && Number.isFinite(Date.parse(value)), 'invalid-provider-evidence'); return value; }
+
+/** Discover destinations and bind a human choice. Status reads never create journal entries. */
+export async function createTrackerTransition(inputConfig) {
+  const input = captureRecord(inputConfig, new Set(['repository', 'target', 'mergeReceipt', 'providerId', 'baseUrl', 'headers', 'transport', 'clock', 'timeoutMs', 'persistedPayload']), ['repository', 'target', 'mergeReceipt', 'providerId', 'baseUrl', 'transport'], 'invalid-config');
+  const supplied = plain(input.repository), repository = parseRepositoryRemote(supplied.url);
+  ensure(hash(repository) === hash(supplied));
+  const target = plain(input.target); exact(target, ['kind', 'issueKey', 'issueUrl', 'requestDigest']);
+  ensure(['jira', 'linear'].includes(target.kind) && typeof target.issueKey === 'string' && KEY.test(target.issueKey));
+  digest(target.requestDigest); id(input.providerId);
+  const jira = target.kind === 'jira';
+  let url; try { url = new URL(target.issueUrl); } catch { ensure(false); }
+  ensure(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && url.href === target.issueUrl);
+  ensure(jira ? /^https:\/\/[a-z0-9][a-z0-9-]*\.atlassian\.net$/.test(input.baseUrl)
+    && target.issueUrl === `${input.baseUrl}/browse/${target.issueKey}`
+    : input.baseUrl === 'https://api.linear.app' && url.origin === 'https://linear.app'
+      && new RegExp(`^/[^/]+/issue/${target.issueKey}(?:/[^/]+)?/?$`).test(url.pathname));
+  const merged = plain(input.mergeReceipt);
+  validateReceipt(merged, { action: 'merge', digest: digest(merged.operationDigest), candidate: { headSha: sha(merged.headSha) } });
+  const prefix = `${repository.url}/${repository.provider === 'github' ? 'pull' : repository.provider === 'gitlab' ? '-/merge_requests' : 'pull-requests'}/`;
+  const reviewNumber = Number(merged.resourceUrl.slice(prefix.length));
+  ensure(Number.isSafeInteger(reviewNumber) && reviewNumber > 0 && merged.resourceUrl === prefix + reviewNumber);
+  const clock = input.clock ?? (() => new Date().toISOString()); ensure(typeof clock === 'function');
+  const http = createProviderHttpClient({ provider: target.kind, baseUrl: input.baseUrl, transport: input.transport,
+    ...(input.headers === undefined ? {} : { headers: input.headers }), ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }) });
+  const internal = value => { ensure(typeof value === 'string' && (jira ? NUMBER : UUID).test(value), 'invalid-provider-evidence'); return value; };
+  function owner(value) { internal(value?.id); ensure(value.key === target.issueKey.split('-')[0], 'changed-facts'); return plain({ id: value.id, key: value.key }); }
+  function state(value, expectedOwner) {
+    internal(value?.id);
+    if (!jira) ensure(hash(owner(value.team)) === hash(expectedOwner), 'changed-facts');
+    return plain({ id: value.id, name: label(value.name), type: label(jira ? value.statusCategory?.key : value.type) });
+  }
+  async function graphql(query, variables) {
+    const result = (await http.request({ method: 'POST', path: '/graphql', wireBody: createProviderReadBody({ provider: 'linear', payload: { query, variables } }) })).data;
+    ensure(result && !Object.hasOwn(result, 'errors') && result.data && typeof result.data === 'object', 'invalid-provider-evidence');
+    return result.data;
+  }
+  async function issue(selected, expected) {
+    const raw = jira ? (await http.request({ method: 'GET', path: `/rest/api/3/issue/${encodeURIComponent(selected)}?fields=updated,project,status` })).data
+      : (await graphql(ISSUE_QUERY, { id: selected })).issue;
+    internal(raw?.id);
+    ensure((jira ? raw.key : raw.identifier) === target.issueKey && (jira || raw.url === target.issueUrl), 'changed-facts');
+    const identity = owner(jira ? raw.fields?.project : raw.team);
+    if (expected) ensure(raw.id === expected.id && hash(identity) === hash(expected.owner), 'changed-facts');
+    return plain({ id: raw.id, key: target.issueKey, owner: identity,
+      revision: revision(jira ? raw.fields.updated : raw.updatedAt), state: state(jira ? raw.fields.status : raw.state, identity) });
+  }
+  async function destinations(current) {
+    if (jira) {
+      const raw = (await http.request({ method: 'GET', path: `/rest/api/3/issue/${current.id}/transitions?expand=transitions.fields` })).data;
+      ensure(Array.isArray(raw?.transitions) && raw.transitions.length <= 100, 'invalid-provider-evidence');
+      const result = raw.transitions.map(value => {
+        internal(value.id); label(value.name);
+        ensure(typeof value.hasScreen === 'boolean' && value.fields && typeof value.fields === 'object' && !Array.isArray(value.fields), 'invalid-provider-evidence');
+        const fields = Object.values(value.fields);
+        ensure(fields.length <= 100 && fields.every(field => field && typeof field.required === 'boolean'), 'invalid-provider-evidence');
+        const eligible = !value.hasScreen && fields.every(field => !field.required);
+        return plain({ id: value.id, name: value.name, state: state(value.to, current.owner), eligible,
+          reason: eligible ? null : 'requires-fields-or-screen', metadataDigest: hash({ to: value.to, fields: value.fields, hasScreen: value.hasScreen }) });
+      });
+      ensure(new Set(result.map(value => value.id)).size === result.length, 'invalid-provider-evidence');
+      return result;
+    }
+    const result = [], ids = new Set(), cursors = new Set(); let cursor = null;
+    for (let page = 0; page < 10; page++) {
+      const connection = (await graphql(STATES_QUERY, { filter: { team: { id: { eq: current.owner.id } } }, cursor })).workflowStates;
+      ensure(Array.isArray(connection?.nodes) && connection.nodes.length <= 100 && typeof connection.pageInfo?.hasNextPage === 'boolean', 'invalid-provider-evidence');
+      for (const value of connection.nodes) {
+        const normalized = state(value, current.owner);
+        ensure(!ids.has(normalized.id), 'invalid-provider-evidence'); ids.add(normalized.id);
+        result.push(plain({ id: normalized.id, name: normalized.name, state: normalized, eligible: true, reason: null, metadataDigest: hash({ state: normalized, owner: current.owner }) }));
+      }
+      if (!connection.pageInfo.hasNextPage) return result;
+      cursor = connection.pageInfo.endCursor;
+      ensure(connection.nodes.length > 0 && typeof cursor === 'string' && /^[A-Za-z0-9._~+=/-]{1,512}$/.test(cursor) && !cursors.has(cursor), 'invalid-provider-evidence'); cursors.add(cursor);
+    }
+    ensure(false, 'invalid-provider-evidence');
+  }
+  const binding = { ...target, providerId: input.providerId, endpoint: input.baseUrl, mergeCommit: merged.commitSha, reviewUrl: merged.resourceUrl, assurance: 'precheck-readback' };
+  function validSaved(payload) {
+    exact(payload, [...Object.keys(binding), 'issue', 'destination']);
+    const { issue: savedIssue, destination, ...rest } = payload;
+    ensure(hash(rest) === hash(binding), 'changed-facts');
+    exact(savedIssue, ['id', 'key', 'owner', 'revision', 'state']); internal(savedIssue.id); owner(savedIssue.owner); revision(savedIssue.revision);
+    ensure(savedIssue.key === target.issueKey); exact(savedIssue.state, ['id', 'name', 'type']); internal(savedIssue.state.id); label(savedIssue.state.name); label(savedIssue.state.type);
+    exact(destination, ['id', 'name', 'state', 'eligible', 'reason', 'metadataDigest']); internal(destination.id); label(destination.name); digest(destination.metadataDigest);
+    exact(destination.state, ['id', 'name', 'type']); internal(destination.state.id); label(destination.state.name); label(destination.state.type);
+    ensure(destination.eligible === true && destination.reason === null);
+    if (!jira) ensure(destination.id === destination.state.id);
+  }
+  function prepare(payload) {
+    validSaved(payload);
+    function candidate(value) { validateCandidate(value); ensure(hash(value.repository) === hash(repository) && value.headSha === merged.headSha && (value.reviewNumber === null || value.reviewNumber === reviewNumber), 'changed-facts'); }
+    async function observe(value) {
+      candidate(value);
+      const current = await issue(payload.issue.id, payload.issue);
+      const choices = await destinations(current);
+      const selected = choices.find(choice => choice.id === payload.destination.id);
+      ensure(hash(current) === hash(payload.issue) && selected && hash(selected) === hash(payload.destination), 'changed-facts');
+      const evidenceDigest = hash({ current, selected, binding });
+      return plain({ repositoryUrl: repository.url, sourceBranch: value.sourceBranch, targetBranch: value.targetBranch, headSha: value.headSha, baseSha: merged.commitSha,
+        review: { number: reviewNumber, state: 'merged', url: merged.resourceUrl, headSha: value.headSha },
+        checks: { headSha: value.headSha, policy: 'unknown', satisfied: null, evidenceDigest },
+        reviews: { headSha: value.headSha, policy: 'unknown', satisfied: null, evidenceDigest }, observedAt: timestamp(clock()) });
+    }
+    function operation(value) { const op = plain(value); candidate(op.candidate); digest(op.digest); ensure(op.action === 'tracker-transition' && hash(op.payload) === hash(payload) && hash(op.mergeReceipt) === hash(merged), 'changed-facts'); return op; }
+    async function reconcile(value) {
+      try {
+        const op = operation(value), current = await issue(payload.issue.id, payload.issue);
+        ensure(hash(current.state) === hash(payload.destination.state), 'unverified-effect');
+        return { status: 'succeeded', receipt: plain({ status: 'succeeded', operationDigest: op.digest, headSha: op.candidate.headSha, commitSha: merged.commitSha,
+          resourceUrl: target.issueUrl, evidenceDigest: hash({ payload, observed: current, assurance: 'desired-state-observed-not-exclusive-causation' }) }) };
+      } catch { return { status: 'unknown' }; }
+    }
+    async function dispatch(value, context) {
+      const op = operation(value), ctx = plain(context); exact(ctx, ['deadline']);
+      const deadline = Date.parse(timestamp(ctx.deadline)), timely = () => ensure(Date.parse(timestamp(clock())) < deadline, 'dispatch-expired');
+      timely(); ensure(hash(payload.issue.state) !== hash(payload.destination.state), 'already-desired');
+      ensure(factsDigest(await observe(op.candidate)) === op.factsDigest, 'changed-facts');
+      const wireBody = createProviderWireBody({ provider: target.kind, action: 'tracker-transition', resourceId: payload.issue.id,
+        expectedState: payload.issue.state.id, expectedVersion: payload.issue.revision, idempotencyKey: op.digest,
+        payload: jira ? { transitionId: payload.destination.id } : { issueId: payload.issue.id, stateId: payload.destination.state.id } });
+      timely(); const remaining = deadline - Date.parse(timestamp(clock())); ensure(remaining > 0, 'dispatch-expired');
+      const controller = new AbortController(), timer = setTimeout(() => controller.abort(), remaining);
+      try {
+        const response = await http.request({ method: 'POST', path: jira ? `/rest/api/3/issue/${payload.issue.id}/transitions` : '/graphql', wireBody, signal: controller.signal });
+        ensure(jira ? response.status === 204 : response.data && !Object.hasOwn(response.data, 'errors') && response.data.data?.issueUpdate?.success === true && response.data.data.issueUpdate.issue?.id === payload.issue.id, 'unverified-effect');
+      } finally { clearTimeout(timer); }
+      const outcome = await reconcile(op); ensure(outcome.status === 'succeeded', 'unverified-effect'); return outcome.receipt;
+    }
+    const executor = createTrustedDeliveryExecutor({ provider: repository.provider,
+      capabilities: [{ action: 'tracker-transition', conditionalHead: false, verifiesDesiredState: true, reconcile: true }], observe, dispatch, reconcile });
+    return Object.freeze({ executor, payload, alreadyDesired: hash(payload.issue.state) === hash(payload.destination.state),
+      preview: `${target.issueKey}: ${payload.issue.state.name} -> ${payload.destination.state.name} (${payload.destination.name})` });
+  }
+  if (input.persistedPayload !== undefined) {
+    const payload = plain(input.persistedPayload); validSaved(payload); await issue(payload.issue.id, payload.issue); return prepare(payload);
+  }
+  const current = await issue(target.issueKey), available = await destinations(current);
+  const status = plain({ target, current: current.state, issueRevision: current.revision, destinations: available });
+  return Object.freeze({ status, async select(destinationId) {
+    const destination = available.find(value => value.id === destinationId);
+    ensure(destination?.eligible === true, 'unsupported-transition');
+    return prepare(plain({ ...binding, issue: current, destination }));
+  } });
+}

package/src/delivery/tracker.js

@@ -0,0 +1,164 @@
+import { createProviderHttpClient } from '../adapters/http.js';
+import { captureRecord, createProviderReadBody, 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';
+const KEY = /^[A-Z][A-Z0-9]{0,31}-[1-9][0-9]{0,15}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMBER = /^[1-9][0-9]{0,19}$/;
+const ISSUE_QUERY = 'query RivetDeliveryIssue($id: String!) { issue(id: $id) { id identifier url updatedAt team { id key } } }';
+const COMMENTS_QUERY = 'query RivetDeliveryComments($id: String!, $cursor: String) { issue(id: $id) { id comments(first: 100, after: $cursor) { nodes { id body } pageInfo { hasNextPage endCursor } } } }';
+function safeUrl(value) {
+  ensure(typeof value === 'string' && value.length <= 2048 && !/[\s<>`\[\]()]/.test(value));
+  let url;
+  try { url = new URL(value); } catch { ensure(false); }
+  ensure(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && url.href === value);
+  return url;
+}
+function revision(value) {
+  ensure(typeof value === 'string' && value.length <= 64 && Number.isFinite(Date.parse(value)), 'invalid-provider-evidence');
+  return value;
+}
+function document(body) {
+  return { type: 'doc', version: 1, content: body.split('\n').filter(Boolean).map(text => ({type:'paragraph',content:[{type:'text',text}]})) };
+}
+
+export async function createTrackerDelivery(inputConfig) {
+  ensure(inputConfig && typeof inputConfig === 'object' && !Array.isArray(inputConfig));
+  for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(inputConfig))) ensure(Object.hasOwn(descriptor, 'value'));
+  const input = captureRecord(inputConfig,
+    new Set(['repository','target','mergeReceipt','deploymentReceipt','providerId','baseUrl','headers','transport','clock','timeoutMs','persistedPayload']),
+    ['repository','target','mergeReceipt','deploymentReceipt','providerId','baseUrl','transport'], 'invalid-config');
+  const supplied = plain(input.repository), repository = parseRepositoryRemote(supplied.url);
+  ensure(hash(repository) === hash(supplied));
+  const target = plain(input.target);
+  exact(target,['kind','issueKey','issueUrl','requestDigest']);
+  ensure(['jira','linear'].includes(target.kind) && typeof target.issueKey === 'string' && KEY.test(target.issueKey));
+  digest(target.requestDigest); id(input.providerId);
+  ensure(typeof input.baseUrl === 'string');
+  const issueUrl = safeUrl(target.issueUrl), endpoint = safeUrl(input.baseUrl.endsWith('/') ? input.baseUrl : input.baseUrl + '/');
+  // Keep credentials scoped to the known tenant/API; no arbitrary custom hosts.
+  ensure(target.kind === 'jira'
+    ? /^https:\/\/[a-z0-9][a-z0-9-]*\.atlassian\.net\/$/.test(endpoint.href)
+      && target.issueUrl === `${endpoint.origin}/browse/${target.issueKey}`
+    : endpoint.origin === 'https://api.linear.app' && endpoint.pathname === '/'
+      && issueUrl.origin === 'https://linear.app'
+      && new RegExp(`^/[^/]+/issue/${target.issueKey}(?:/[^/]+)?/?$`).test(issueUrl.pathname));
+  const baseUrl = endpoint.origin;
+  const merged = plain(input.mergeReceipt);
+  validateReceipt(merged,{action:'merge',digest:digest(merged.operationDigest),candidate:{headSha:sha(merged.headSha)}});
+  safeUrl(merged.resourceUrl);
+  const reviewPrefix = `${repository.url}${repository.provider === 'github' ? '/pull/' : repository.provider === 'gitlab' ? '/-/merge_requests/' : '/pull-requests/'}`;
+  const reviewNumber = Number(merged.resourceUrl.slice(reviewPrefix.length));
+  ensure(Number.isSafeInteger(reviewNumber) && reviewNumber > 0 && merged.resourceUrl === reviewPrefix + reviewNumber);
+  let deploymentUrl = null;
+  if (input.deploymentReceipt !== null) {
+    const deployed = plain(input.deploymentReceipt);
+    validateReceipt(deployed,{action:'deploy',digest:digest(deployed.operationDigest),candidate:{headSha:merged.headSha}});
+    ensure(deployed.commitSha === merged.commitSha); safeUrl(deployed.resourceUrl); deploymentUrl = deployed.resourceUrl;
+  }
+  const clock = input.clock ?? (()=>new Date().toISOString()); ensure(typeof clock === 'function');
+  const http = createProviderHttpClient({provider:target.kind,baseUrl,transport:input.transport,maxItems:1000,maxPages:10,
+    ...(input.headers === undefined ? {} : {headers:input.headers}), ...(input.timeoutMs === undefined ? {} : {timeoutMs:input.timeoutMs})});
+  async function graphql(query,variables) {
+    const response = (await http.request({method:'POST',path:'/graphql',wireBody:createProviderReadBody({provider:'linear',payload:{query,variables}})})).data;
+    ensure(response && !Object.hasOwn(response,'errors') && response.data && typeof response.data === 'object','invalid-provider-evidence');
+    return response.data;
+  }
+  const internal = value => { ensure(typeof value === 'string' && (target.kind === 'jira' ? NUMBER : UUID).test(value), 'invalid-provider-evidence'); return value; };
+  async function issue(selected, expected) {
+    if (target.kind === 'jira') {
+      const value = (await http.request({method:'GET',path:`/rest/api/3/issue/${encodeURIComponent(selected)}?fields=updated,project`})).data;
+      internal(value?.id);
+      ensure(value.key === target.issueKey && (!expected || value.id === expected)
+        && typeof value.fields?.project?.id === 'string' && NUMBER.test(value.fields.project.id)
+        && value.fields.project.key === target.issueKey.split('-')[0], 'changed-facts');
+      return plain({id:value.id,key:value.key,project:{id:value.fields.project.id,key:value.fields.project.key},revision:revision(value.fields.updated)});
+    }
+    const value = (await graphql(ISSUE_QUERY,{id:selected})).issue;
+    internal(value?.id);
+    ensure(value.identifier === target.issueKey && value.url === target.issueUrl && (!expected || value.id === expected)
+      && typeof value.team?.id === 'string' && UUID.test(value.team.id)
+      && value.team.key === target.issueKey.split('-')[0], 'changed-facts');
+    return plain({id:value.id,key:value.identifier,team:{id:value.team.id,key:value.team.key},revision:revision(value.updatedAt)});
+  }
+  const binding = {...target,providerId:input.providerId,endpoint:baseUrl,mergeCommit:merged.commitSha,reviewUrl:merged.resourceUrl,deploymentUrl};
+  let payload;
+  if (input.persistedPayload !== undefined) {
+    const stored = plain(input.persistedPayload);
+    exact(stored,[...Object.keys(binding),'issueInternalId']);
+    const {issueInternalId,...priorBinding} = stored;
+    internal(issueInternalId); ensure(hash(binding) === hash(priorBinding),'changed-facts');
+    await issue(issueInternalId,issueInternalId); payload = stored;
+  } else {
+    const source = await issue(target.issueKey);
+    payload = plain({...binding,issueInternalId:source.id});
+  }
+  const preview = `Rivet delivery update\nMerged commit: ${merged.commitSha}\nReview: ${merged.resourceUrl}${deploymentUrl ? `\nVerified deployment: ${deploymentUrl}` : ''}`;
+  function candidate(value) {
+    validateCandidate(value);
+    ensure(hash(value.repository) === hash(repository) && value.headSha === merged.headSha
+      && (value.reviewNumber === null || value.reviewNumber === reviewNumber),'changed-facts');
+  }
+  async function observe(value) {
+    candidate(value);
+    const current = await issue(payload.issueInternalId,payload.issueInternalId), evidenceDigest = hash({current,target,payload});
+    return plain({repositoryUrl:repository.url,sourceBranch:value.sourceBranch,targetBranch:value.targetBranch,headSha:value.headSha,baseSha:merged.commitSha,
+      review:{number:reviewNumber,state:'merged',url:merged.resourceUrl,headSha:value.headSha},
+      checks:{headSha:value.headSha,policy:'unknown',satisfied:null,evidenceDigest},
+      reviews:{headSha:value.headSha,policy:'unknown',satisfied:null,evidenceDigest},observedAt:timestamp(clock())});
+  }
+  function operation(input) {
+    const op=plain(input);candidate(op.candidate);digest(op.digest);
+    ensure(op.action === 'tracker-update' && hash(op.payload) === hash(payload) && hash(op.mergeReceipt) === hash(merged),'changed-facts');
+    return op;
+  }
+  const bodyFor = op => `${preview}\n\nRivet delivery operation: ${op.digest}`;
+  async function comments() {
+    if (target.kind === 'jira') return http.paginate({path:`/rest/api/3/issue/${payload.issueInternalId}/comment?startAt=0&maxResults=100`,mode:'jira-offset',itemsKey:'comments',identityKey:'id',totalKey:'total'});
+    const output=[],seen=new Set(),ids=new Set();let cursor=null;
+    for(let page=0;page<10;page++) {
+      const value=(await graphql(COMMENTS_QUERY,{id:payload.issueInternalId,cursor})).issue;
+      ensure(value?.id === payload.issueInternalId && Array.isArray(value.comments?.nodes),'invalid-provider-evidence');
+      const {nodes,pageInfo}=value.comments;
+      ensure(nodes.length <= 100 && pageInfo && typeof pageInfo.hasNextPage === 'boolean','invalid-provider-evidence');
+      for(const item of nodes) {ensure(typeof item?.id === 'string' && UUID.test(item.id) && !ids.has(item.id),'invalid-provider-evidence');ids.add(item.id);output.push(item);}
+      if(pageInfo.hasNextPage === false)return output;
+      ensure(nodes.length > 0 && typeof pageInfo.endCursor === 'string' && /^[A-Za-z0-9._~+=/-]{1,512}$/.test(pageInfo.endCursor) && !seen.has(pageInfo.endCursor),'invalid-provider-evidence');
+      cursor=pageInfo.endCursor;seen.add(cursor);
+    }
+    ensure(false,'invalid-provider-evidence');
+  }
+  async function reconcile(input) {
+    try {
+      const op=operation(input),current=await issue(payload.issueInternalId,payload.issueInternalId),all=await comments();
+      const expected=target.kind === 'jira' ? document(bodyFor(op)) : bodyFor(op);
+      for(const item of all) ensure(typeof item?.id === 'string' && (target.kind==='jira'?NUMBER:UUID).test(item.id)
+        && (target.kind==='jira' ? item.body?.type==='doc' && item.body.version===1 && Array.isArray(item.body.content) : typeof item.body==='string'),'invalid-provider-evidence');
+      const marker = `Rivet delivery operation: ${op.digest}`;
+      const matches=all.filter(item=>JSON.stringify(item.body).includes(marker));
+      ensure(matches.length===1 && hash(matches[0].body)===hash(expected),'unverified-effect');
+      return {status:'succeeded',receipt:plain({status:'succeeded',operationDigest:op.digest,headSha:op.candidate.headSha,commitSha:merged.commitSha,
+        resourceUrl:target.issueUrl,evidenceDigest:hash({issue:current,comment:matches[0],payload})})};
+    }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:target.kind,action:target.kind==='jira'?'comment':'delivery-comment',resourceId:payload.issueInternalId,
+      expectedState:'merged',expectedVersion:merged.commitSha,idempotencyKey:op.digest,
+      payload:target.kind==='jira'?{body:document(bodyFor(op))}:{issueId:payload.issueInternalId,body:bodyFor(op)}});
+    timely();const remaining=deadline-Date.parse(timestamp(clock()));ensure(remaining>0,'dispatch-expired');
+    const controller=new AbortController(),timer=setTimeout(()=>controller.abort(),remaining);
+    try {
+      const response=(await http.request({method:'POST',path:target.kind==='jira'?`/rest/api/3/issue/${payload.issueInternalId}/comment`:'/graphql',wireBody,signal:controller.signal})).data;
+      if(target.kind==='linear')ensure(response && !Object.hasOwn(response,'errors') && response.data?.commentCreate?.success===true,'unverified-effect');
+    } finally {clearTimeout(timer)}
+    const result=await reconcile(op);ensure(result.status==='succeeded','unverified-effect');return result.receipt;
+  }
+  // conditionalHead binds comment content to the confirmed merge commit; it does
+  // not claim atomic issue version checks or native comment idempotency.
+  const executor=createTrustedDeliveryExecutor({provider:repository.provider,capabilities:[{action:'tracker-update',conditionalHead:true,reconcile:true}],observe,dispatch,reconcile});
+  return Object.freeze({executor,payload,preview});
+}

package/src/discovery/git.js

@@ -0,0 +1,85 @@
+import { resolve } from 'node:path';
+
+import { runArgv } from './tools.js';
+
+async function git(runner, cwd, args) {
+  try {
+    return await runner('git', args, {
+      cwd,
+      shell: false,
+      timeoutMs: 3_000,
+      maxOutputBytes: 32 * 1024,
+    });
+  } catch {
+    return { code: 1, stdout: '', stderr: '' };
+  }
+}
+
+function pathsFromWorktrees(output) {
+  if (typeof output !== 'string' || !output.includes('\0')) return null;
+  const records = output.split('\0\0').filter(Boolean);
+  const paths = [];
+  for (const record of records) {
+    const fields = record.split('\0').filter(Boolean);
+    if (!fields[0]?.startsWith('worktree ') || fields[0].length === 'worktree '.length) return null;
+    paths.push(resolve(fields[0].slice('worktree '.length)));
+  }
+  return paths.length > 0 ? paths : null;
+}
+
+export async function discoverGit(projectRoot, options = {}) {
+  const cwd = resolve(projectRoot);
+  const runner = options.runner ?? runArgv;
+  const rootResult = await git(runner, cwd, ['rev-parse', '--show-toplevel']);
+  if (rootResult.code !== 0) {
+    return {
+      repository: false,
+      root: null,
+      currentBranch: null,
+      defaultBranch: null,
+      detached: false,
+      dirty: false,
+      baseFreshness: 'not_checked',
+      worktrees: [],
+      occupiedCandidatePaths: [],
+      worktreeCheck: { checked: false, error: 'not_repository' },
+    };
+  }
+  const [branchResult, statusResult, defaultResult, worktreeResult] = await Promise.all([
+    git(runner, cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']),
+    git(runner, cwd, ['status', '--porcelain']),
+    git(runner, cwd, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']),
+    git(runner, cwd, ['worktree', 'list', '--porcelain', '-z']),
+  ]);
+  const currentBranch = branchResult.code === 0 ? branchResult.stdout.trim() || null : null;
+  const remoteHead = defaultResult.code === 0 ? defaultResult.stdout.trim() : '';
+  const defaultBranch = options.defaultBranch ?? (remoteHead.replace(/^origin\//, '')
+    || (currentBranch === 'main' || currentBranch === 'master' ? currentBranch : 'main'));
+  const defaultBranchSource = options.defaultBranch !== undefined ? 'configuration' : remoteHead
+    ? 'remote_tracking' : (currentBranch === 'main' || currentBranch === 'master') ? 'current_branch' : 'default';
+  const freshnessResult = await git(runner, cwd, [
+    'rev-list', '--left-right', '--count', `${defaultBranch}...refs/remotes/origin/${defaultBranch}`,
+  ]);
+  let baseFreshness = 'not_checked';
+  if (freshnessResult.code === 0 && /^\d+\s+\d+$/.test(freshnessResult.stdout.trim())) {
+    const [ahead = 0, behind = 0] = freshnessResult.stdout.trim().split(/\s+/).map(Number);
+    baseFreshness = behind > 0 ? 'behind' : ahead > 0 ? 'ahead' : 'fresh';
+  }
+  const worktrees = worktreeResult.code === 0 ? pathsFromWorktrees(worktreeResult.stdout) : null;
+  const worktreeError = worktreeResult.timedOut === true
+    ? 'timeout' : worktreeResult.code !== 0 ? 'unavailable' : worktrees === null ? 'malformed' : null;
+  const candidates = (options.candidatePaths ?? []).map(path => resolve(path));
+  return {
+    repository: true,
+    root: resolve(rootResult.stdout.trim()),
+    currentBranch,
+    defaultBranch,
+    defaultBranchSource,
+    detached: currentBranch === null,
+    dirty: statusResult.code !== 0 || statusResult.stdout.trim().length > 0,
+    baseFreshness,
+    worktrees: worktrees ?? [],
+    occupiedCandidatePaths: worktrees === null ? null : candidates.filter(path => worktrees.includes(path)),
+    worktreeCheck: worktreeError ? { checked: false, error: worktreeError } : { checked: true },
+  };
+}

package/src/discovery/portable.js

@@ -0,0 +1,108 @@
+import {basename,join} from 'node:path';
+import {compileProjectCommands} from '../config/commands.js';
+
+export class ProjectChecksRequiredError extends Error {
+  constructor(message = 'No project verification commands were detected. Run interactive rivet setup --write to choose a check, or pass --checks-json with your project commands, for example: {"test":["python3","-m","pytest"]}. No files were written.') {
+    super(message);
+    this.code = 'MISSING_CONFIGURATION';
+  }
+}
+
+export function parseProjectChecks(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || Buffer.byteLength(value) > 16384) throw new ProjectChecksRequiredError('Option --checks-json must be a bounded JSON object of project check commands.');
+  try { return JSON.parse(value); }
+  catch { throw new ProjectChecksRequiredError('Option --checks-json must contain valid JSON, for example: {"test":["python3","-m","pytest"]}.'); }
+}
+
+export function parseProjectDependencies(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || Buffer.byteLength(value) > 16384) throw new ProjectChecksRequiredError('Option --dependencies-json must be a bounded JSON dependency plan.');
+  try {
+    const parsed=JSON.parse(value);
+    if(!parsed || typeof parsed!=='object' || Array.isArray(parsed))throw new Error('Invalid dependency object');
+    return parsed;
+  }
+  catch { throw new ProjectChecksRequiredError('Option --dependencies-json must contain valid JSON with inputs, provides, and ordered steps.'); }
+}
+
+// Tokenize one argv command for the setup prompt. No expansion or shell dispatch.
+export function parseCheckCommand(value) {
+  if(typeof value!=='string' || value.length>16384 || /[\u0000-\u001f\u007f]/.test(value)) throw new ProjectChecksRequiredError('Enter one bounded verification command without control characters.');
+  const argv=[];let token='',quote=null,escaped=false,started=false;
+  for(const char of value.trim()) {
+    if(escaped) {token+=char;escaped=false;started=true;continue;}
+    if(char==='\\' && quote!=="'") {escaped=true;started=true;continue;}
+    if(quote) {if(char===quote)quote=null;else token+=char;started=true;continue;}
+    if(char==='"'||char==="'") {quote=char;started=true;continue;}
+    if(/\s/.test(char)) {if(started){argv.push(token);token='';started=false;}continue;}
+    if(/[;&|<>`]/.test(char)) throw new ProjectChecksRequiredError('Enter one command without shell operators. Configure separate argv steps with --checks-json for multiple checks.');
+    token+=char;started=true;
+  }
+  if(quote||escaped)throw new ProjectChecksRequiredError('The verification command has an unfinished quote or escape.');
+  if(started)argv.push(token);
+  if(!argv.length)throw new ProjectChecksRequiredError();
+  return argv;
+}
+
+export function discoverPortableProject(root, {fs, inspect, read, checks}) {
+  const metadata = new Map();
+  let totalBytes=0;
+  for (const name of ['manage.py','pyproject.toml','requirements.txt','setup.cfg','setup.py','Pipfile','uv.lock','poetry.lock','go.mod','Cargo.toml','Makefile','pom.xml','build.gradle','composer.json','Gemfile','AGENTS.md']) {
+    if(['uv.lock','poetry.lock'].includes(name)) {
+      const entry=fs.lstatSync(join(root,name),{throwIfNoEntry:false});
+      if(entry) {if(!entry.isFile()||entry.isSymbolicLink())throw new ProjectChecksRequiredError('Project lock metadata must be a regular file.');metadata.set(name,'');}
+      continue;
+    }
+    const file=inspect(root,name,fs,false);
+    if(file) {
+      totalBytes+=file.size;
+      if(totalBytes>2*1024*1024)throw new ProjectChecksRequiredError('Project metadata exceeds the discovery read limit. Use smaller metadata files.');
+      metadata.set(name,read(file,fs));
+    }
+  }
+  let framework='other', language='other', packageManager='other', source='explicit project checks';
+  let commands={};
+  const group=argv=>({steps:[{cwd:'.',argv}]});
+  if(metadata.has('manage.py') || ['pyproject.toml','requirements.txt','setup.cfg','setup.py','Pipfile'].some(name=>metadata.has(name))) {
+    language='python';packageManager=metadata.has('uv.lock')?'uv':metadata.has('poetry.lock')?'poetry':'pip';
+    if(metadata.has('manage.py')) {
+      framework='django';source='manage.py (Django convention; review before use)';
+      commands={check:group(['python3','manage.py','check']),test:group(['python3','manage.py','test'])};
+    } else if(['pyproject.toml','requirements.txt','setup.cfg'].some(name=>/\bpytest\b/.test(metadata.get(name)??''))) {
+      source='Python metadata (pytest convention; review before use)';
+      commands={test:group(['python3','-m','pytest'])};
+    }
+  } else if(metadata.has('go.mod')) {
+    language='go';packageManager='go';source='go.mod (Go convention; review before use)';
+    commands={build:group(['go','build','./...']),test:group(['go','test','./...'])};
+  } else if(metadata.has('Cargo.toml')) {
+    language='rust';packageManager='cargo';source='Cargo.toml (Cargo convention; review before use)';
+    commands={build:group(['cargo','build']),test:group(['cargo','test'])};
+  }
+  if(checks !== undefined) {
+    if(!checks || typeof checks!=='object' || Array.isArray(checks)) throw new ProjectChecksRequiredError('Project checks must be a JSON object mapping test/check/build/lint/typecheck to argv arrays or step groups.');
+    commands=Object.fromEntries(Object.entries(checks).map(([key,value])=>[key,Array.isArray(value)?group(value):value]));
+    source='explicit --checks-json';
+  }
+  let dependencies;
+  if (language === 'python' && metadata.has('requirements.txt') && checks === undefined) {
+    const python='./.rivet-deps/venv/bin/python';
+    dependencies={inputs:['requirements.txt'],provides:[python],steps:[
+      {cwd:'.',argv:['python3','-m','venv','.rivet-deps/venv']},
+      {cwd:'.',argv:[python,'-m','pip','--isolated','install','--require-virtualenv','--no-user','-r','requirements.txt']},
+    ]};
+    for(const group of Object.values(commands)) for(const step of group.steps) if(step.argv[0]==='python3')step.argv[0]=python;
+  }
+  if(!commands.test && !commands.check) throw new ProjectChecksRequiredError();
+  const name=basename(root).normalize('NFKC').slice(0,120);
+  const id=name.toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^-|-$/g,'').slice(0,60).replace(/-$/,'');
+  const projectId=(/^[a-z]/.test(id)?id:`project-${id||'local'}`).slice(0,64).replace(/-$/,'');
+  const proposal={schemaVersion:3,id:projectId,name,stack:{framework,language,packageManager},commands,...(dependencies?{dependencies}:{})};
+  try { compileProjectCommands(proposal); }
+  catch { throw new ProjectChecksRequiredError('Project checks are invalid. Use bounded argv arrays with executable names, safe relative working directories, and at least one test or check command. Shell commands are not supported.'); }
+  const provenance={id:'project directory basename',name:'project directory basename','stack.framework':source,'stack.language':source,'stack.packageManager':source,'features.storybook':'not detected','features.playwright':'not detected'};
+  for(const [key,group] of Object.entries(commands)) group.steps.forEach((_,index)=>{provenance[`commands.${key}.steps[${index}]`]=source;});
+  if(dependencies)provenance.dependencies='requirements.txt (isolated Python environment proposal; review before installation)';
+  return {root,proposal,inspectedFiles:[...metadata.keys()],features:{storybook:false,playwright:false},architectureHints:metadata.has('AGENTS.md')?['AGENTS.md']:[],existingConfig:fs.existsSync(`${root}/.rivet`),warnings:[{code:'environment-preparation',message:dependencies?'Review the proposed dependency steps. Installation requires separate approval in each isolated checkout.':'Review the proposed commands. Configure dependency installation steps when this project needs environment preparation.'}],unresolved:[],provenance};
+}