@agilno-tech/rivet 0.1.0-alpha.0

package/src/delivery/service.js

@@ -0,0 +1,400 @@
+import { randomUUID } from 'node:crypto';
+import { evaluateAuthority } from '../policy/authority.js';
+import {
+  ACTIONS,
+  candidate,
+  digest,
+  ensure,
+  exact,
+  fail,
+  factsDigest,
+  hash,
+  id,
+  mergeReceiptFor,
+  observation,
+  plain,
+  ready,
+  timestamp,
+  validateReceipt,
+} from './contract.js';
+import { isDeliveryStore } from './store.js';
+const executors = new WeakSet();
+const inFlight = new Map();
+
+// Only trusted application code may create an executor. A succeeded receipt must
+// describe a provider-verified effect for the exact operation; not-applied means
+// terminal proof that no effect occurred or can later occur. An eventually
+// consistent absence check is not sufficient. Native transports are not qualified
+// by this constructor: mutation guarantees and reconciliation remain obligations
+// of the implementation supplied here. Review creation may explicitly verify
+// creation afterward; tracker transitions may verify the approved desired state.
+// These assurances do not claim atomic compare-and-swap or exclusive causation.
+export function createTrustedDeliveryExecutor(input) {
+  ensure(input && typeof input === 'object');
+  const { provider, capabilities } = input;
+  ensure(['github', 'bitbucket', 'gitlab'].includes(provider));
+  const captured = plain(capabilities);
+  ensure(Array.isArray(captured) && captured.length <= ACTIONS.length);
+  for (const capability of captured) {
+    if (capability.action === 'review-request' && capability.conditionalHead === false) {
+      exact(capability, ['action', 'conditionalHead', 'verifiesCreatedReview', 'reconcile']);
+      ensure(capability.verifiesCreatedReview === true && capability.reconcile === true);
+    } else if (['tracker-transition', 'review-update'].includes(capability.action) && capability.conditionalHead === false) {
+      exact(capability, ['action', 'conditionalHead', 'verifiesDesiredState', 'reconcile']);
+      ensure(capability.verifiesDesiredState === true && capability.reconcile === true);
+    } else {
+      exact(capability, ['action', 'conditionalHead', 'reconcile']);
+      ensure(ACTIONS.includes(capability.action) && capability.conditionalHead === true && capability.reconcile === true);
+    }
+  }
+  ensure(new Set(captured.map((value) => value.action)).size === captured.length);
+  const unavailable = () => fail('executor-unavailable');
+  for (const method of ['observe', 'dispatch', 'reconcile'])
+    ensure(input[method] === undefined || typeof input[method] === 'function');
+  if (captured.length)
+    ensure(
+      typeof input.observe === 'function' &&
+        typeof input.dispatch === 'function' &&
+        typeof input.reconcile === 'function'
+    );
+  const executor = Object.freeze({
+    provider,
+    capabilities: captured,
+    observe: input.observe ?? unavailable,
+    dispatch: input.dispatch ?? unavailable,
+    reconcile: input.reconcile ?? unavailable,
+  });
+  executors.add(executor);
+  return executor;
+}
+export function createDeliveryService(config) {
+  const { store, executor, authority, approvalRegistry, expectedApproverId, subjectId, providerId } = config;
+  ensure(isDeliveryStore(store) && executors.has(executor));
+  id(expectedApproverId);
+  id(subjectId);
+  id(providerId);
+  const clock = config.clock ?? (() => new Date().toISOString());
+  ensure(typeof clock === 'function');
+  const timeoutMs = config.timeoutMs ?? 10000;
+  ensure(Number.isSafeInteger(timeoutMs) && timeoutMs >= 1 && timeoutMs <= 120000);
+  const now = () => timestamp(clock());
+  const active = (state) =>
+    state.operations.some((value) => ['dispatching', 'indeterminate'].includes(value.state));
+  function writable(state) {
+    ensure(!active(state), 'reconciliation-required');
+  }
+  async function load(version) {
+    const state = await store.read();
+    ensure(state !== null, 'missing-state');
+    ensure(state.candidate.repository.provider === executor.provider, 'provider-mismatch');
+    if (version !== undefined)
+      ensure(Number.isSafeInteger(version) && state.version === version, 'version-conflict');
+    return state;
+  }
+  async function save(state, changes) {
+    const { version, ...record } = state;
+    return store.write({ ...record, ...changes, updatedAt: now() }, { expectedVersion: version });
+  }
+  async function bounded(operation) {
+    let timer;
+    try {
+      return await Promise.race([
+        Promise.resolve().then(operation),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function observe(target) {
+    const result = observation(await bounded(() => executor.observe(target)), target);
+    ensure(
+      Date.parse(result.observedAt) <= Date.parse(now()) &&
+        Date.parse(now()) - Date.parse(result.observedAt) <= 300000,
+      'stale-observation'
+    );
+    return result;
+  }
+  function observedStage(state, facts) {
+    if (['merged', 'deployed', 'tracker-updated', 'tracker-status-confirmed'].includes(state.stage)) return state.stage;
+    return ready(facts)
+      ? 'checks-passed'
+      : facts.review ||
+          state.operations.some(
+            (operation) => operation.action === 'review-request' && operation.state === 'succeeded'
+          )
+        ? 'review-requested'
+        : state.operations.some(operation => operation.action === 'branch-publish' && operation.state === 'succeeded') ? 'branch-published' : 'locally-verified';
+  }
+  function allowed(state, action) {
+    ensure(
+      executor.capabilities.some((value) => value.action === action),
+      'unsupported-action'
+    );
+    if (action === 'branch-publish') ensure(state.observation?.publication?.remoteSha === null && ['locally-verified', 'branch-published'].includes(state.stage) && !state.operations.some(op => op.action === action && op.state === 'succeeded'), 'not-ready');
+    else if (action === 'merge')
+      ensure(
+        ready(state.observation) &&
+          !state.operations.some((value) => value.action === 'merge' && value.state === 'succeeded'),
+        'not-ready'
+      );
+    else if (action === 'review-update') ensure(state.observation?.review?.state === 'open' && !state.operations.some(op => op.action === 'merge' && op.state === 'succeeded'), 'not-ready');
+    else if (action === 'review-request')
+      ensure(
+        state.observation?.review === null &&
+          ['locally-verified', 'branch-published'].includes(state.stage) &&
+          !state.operations.some(
+            (operation) => operation.action === 'review-request' && operation.state === 'succeeded'
+          ),
+        'not-ready'
+      );
+    else ensure(
+      state.operations.some((value) => value.action === 'merge' && value.state === 'succeeded') &&
+        !state.operations.some((value) => value.action === action && value.state === 'succeeded'),
+      'not-ready'
+    );
+  }
+  async function initialize(input) {
+    const target = candidate(input);
+    ensure(target.repository.provider === executor.provider);
+    ensure(Date.parse(target.localVerification.verifiedAt) <= Date.parse(now()), 'invalid-verification');
+    return store.exclusive(async () => {
+      ensure((await store.read()) === null, 'state-exists');
+      const at = now();
+      return store.write(
+        {
+          schemaVersion: 1,
+          stage: 'locally-verified',
+          candidate: target,
+          observation: null,
+          proposal: null,
+          operations: [],
+          usedApprovalIds: [],
+          createdAt: at,
+          updatedAt: at,
+        },
+        { expectedVersion: 0 }
+      );
+    });
+  }
+  async function refresh(input) {
+    const request = plain(input);
+    exact(request, ['expectedVersion']);
+    return store.exclusive(async () => {
+      const state = await load(request.expectedVersion);
+      writable(state);
+      const facts = await observe(state.candidate);
+      return save(state, { observation: facts, proposal: null, stage: observedStage(state, facts) });
+    });
+  }
+  async function propose(input) {
+    const request = plain(input);
+    exact(request, ['expectedVersion', 'action', 'payload', 'expiresAt']);
+    ensure(ACTIONS.includes(request.action));
+    ensure(request.payload && typeof request.payload === 'object' && !Array.isArray(request.payload));
+    timestamp(request.expiresAt);
+    ensure(
+      Date.parse(request.expiresAt) > Date.parse(now()) &&
+        Date.parse(request.expiresAt) - Date.parse(now()) <= 3600000,
+      'expired-proposal'
+    );
+    return store.exclusive(async () => {
+      const state = await load(request.expectedVersion);
+      writable(state);
+      ensure(state.observation !== null, 'observation-required');
+      allowed(state, request.action);
+      const facts = await observe(state.candidate);
+      const observed = { ...state, observation: facts };
+      allowed(observed, request.action);
+      const body = {
+        candidate: state.candidate,
+        action: request.action,
+        payload: request.payload,
+        expiresAt: request.expiresAt,
+        factsDigest: factsDigest(facts),
+        nonce: randomUUID(),
+        mergeReceipt: mergeReceiptFor(state.operations, request.action),
+        providerId,
+      };
+      const proposalDigest = hash(body);
+      const resource = `delivery:${proposalDigest}`;
+      return save(state, {
+        observation: facts,
+        proposal: {
+          digest: proposalDigest,
+          action: body.action,
+          payload: body.payload,
+          expiresAt: body.expiresAt,
+          factsDigest: body.factsDigest,
+          nonce: body.nonce,
+          mergeReceipt: body.mergeReceipt,
+          providerId,
+          resource,
+          approvalResource: `${providerId}:${body.action}:${resource}`,
+        },
+      });
+    });
+  }
+  function validateOutcome(receipt, operation) {
+    const result = validateReceipt(receipt, operation);
+    // Historical schema-v1 snapshots remain readable. New post-merge completion
+    // must attest to the actual merge result, including squash/rebase commits.
+    if (['deploy', 'tracker-update', 'tracker-transition'].includes(operation.action))
+      ensure(result.commitSha === operation.mergeReceipt?.commitSha, 'invalid-receipt');
+    return result;
+  }
+  async function finish(state, operation, receipt) {
+    const success = validateOutcome(receipt, operation);
+    const operations = state.operations.map((item) =>
+      item.digest === operation.digest ? { ...item, state: 'succeeded', receipt: success } : item
+    );
+    const stage = {
+      'branch-publish': 'branch-published',
+      'review-request': 'review-requested',
+      'review-update': 'review-requested',
+      merge: 'merged',
+      deploy: 'deployed',
+      'tracker-update': 'tracker-updated',
+      'tracker-transition': 'tracker-status-confirmed',
+    }[operation.action];
+    return save(state, { operations, proposal: null, stage: operations.some(op => op.action === 'tracker-transition' && op.state === 'succeeded') ? 'tracker-status-confirmed' : stage });
+  }
+  async function execute(input) {
+    ensure(input && typeof input === 'object' && !Array.isArray(input));
+    for (const key of Reflect.ownKeys(input)) {
+      ensure(typeof key === 'string' && ['expectedVersion', 'proposalDigest', 'approval'].includes(key));
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      ensure(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+    }
+    const approval = input.approval;
+    const request = plain({ expectedVersion: input.expectedVersion, proposalDigest: input.proposalDigest });
+    ensure(Object.keys(input).length === 3 && Object.hasOwn(input, 'approval'));
+    digest(request.proposalDigest);
+    return store.exclusive(async () => {
+      let state = await load(request.expectedVersion);
+      writable(state);
+      const proposal = state.proposal;
+      ensure(
+        proposal && proposal.digest === request.proposalDigest && proposal.providerId === providerId,
+        'proposal-mismatch'
+      );
+      ensure(Date.parse(proposal.expiresAt) > Date.parse(now()), 'expired-proposal');
+      allowed(state, proposal.action);
+      const facts = await observe(state.candidate);
+      ensure(factsDigest(facts) === proposal.factsDigest, 'changed-facts');
+      allowed({ ...state, observation: facts }, proposal.action);
+      ensure(Date.parse(proposal.expiresAt) > Date.parse(now()), 'expired-proposal');
+      ensure(
+        approval?.singleUse === true && !state.usedApprovalIds.includes(approval.id),
+        'approval-replayed'
+      );
+      const decision = evaluateAuthority(
+        authority,
+        {
+          actorId: subjectId,
+          action: 'provider.write',
+          resource: proposal.resource,
+          providerId,
+          capability: proposal.action,
+        },
+        { approval, approvalRegistry, expectedApproverId, nowMs: Date.parse(now()) }
+      );
+      ensure(decision.decision === 'allow', 'approval-required');
+      const operation = plain({
+        digest: proposal.digest,
+        action: proposal.action,
+        payload: proposal.payload,
+        candidate: state.candidate,
+        factsDigest: proposal.factsDigest,
+        mergeReceipt: proposal.mergeReceipt,
+        approvalId: approval.id,
+        dispatchedAt: now(),
+        state: 'dispatching',
+        receipt: null,
+      });
+      state = await save(state, {
+        operations: [...state.operations, operation],
+        usedApprovalIds: [...state.usedApprovalIds, approval.id],
+        stage: proposal.action === 'merge' ? 'merge-approved' : state.stage,
+      });
+      if (Date.parse(now()) >= Math.min(Date.parse(proposal.expiresAt), Date.parse(approval.expiresAt))) {
+        return save(state, {
+          operations: state.operations.map((value) =>
+            value.digest === operation.digest ? { ...value, state: 'not-applied' } : value
+          ),
+          proposal: null,
+          stage: observedStage(
+            { ...state, stage: proposal.action === 'merge' ? 'checks-passed' : state.stage },
+            facts
+          ),
+        });
+      }
+      let receipt;
+      try {
+        receipt = await bounded(() => {
+          const pending = inFlight;
+          const context = Object.freeze({ deadline: new Date(Math.min(
+            Date.parse(now()) + timeoutMs, Date.parse(proposal.expiresAt), Date.parse(approval.expiresAt)
+          )).toISOString() });
+          const promise = Promise.resolve().then(() => executor.dispatch(operation, context));
+          pending.set(operation.digest, promise);
+          promise.then(
+            () => pending.delete(operation.digest),
+            () => pending.delete(operation.digest)
+          );
+          return promise;
+        });
+        validateOutcome(receipt, operation);
+      } catch {
+        return save(state, {
+          operations: state.operations.map((value) =>
+            value.digest === operation.digest ? { ...value, state: 'indeterminate' } : value
+          ),
+        });
+      }
+      return finish(state, operation, receipt);
+    });
+  }
+  async function reconcile(input) {
+    const request = plain(input);
+    exact(request, ['expectedVersion']);
+    return store.exclusive(async () => {
+      const state = await load(request.expectedVersion);
+      const operation = state.operations.find((value) =>
+        ['dispatching', 'indeterminate'].includes(value.state)
+      );
+      ensure(operation, 'nothing-to-reconcile');
+      // Pending operations retain the exact approved proposal. Bind recovery to
+      // its provider as well as the repository kind before any external read.
+      ensure(state.proposal?.digest === operation.digest && state.proposal.providerId === providerId,
+        'provider-mismatch');
+      ensure(executor.capabilities.some((value) => value.action === operation.action && value.reconcile),
+        'unsupported-action');
+      let result;
+      try {
+        result = inFlight.has(operation.digest)
+          ? { status: 'unknown' }
+          : plain(await bounded(() => executor.reconcile(operation)));
+        if (result.status === 'succeeded') {
+          exact(result, ['status', 'receipt']);
+          validateOutcome(result.receipt, operation);
+        } else {
+          exact(result, ['status']);
+          ensure(['not-applied', 'unknown'].includes(result.status));
+        }
+      } catch {
+        result = { status: 'unknown' };
+      }
+      if (result.status === 'succeeded') return finish(state, operation, result.receipt);
+      const operations = state.operations.map((value) =>
+        value.digest === operation.digest
+          ? { ...value, state: result.status === 'not-applied' ? 'not-applied' : 'indeterminate' }
+          : value
+      );
+      return save(state, { operations, ...(result.status === 'not-applied' ? { proposal: null } : {}) });
+    });
+  }
+  return Object.freeze({ initialize, refresh, propose, execute, reconcile, status: () => store.read() });
+}

package/src/delivery/store.js

@@ -0,0 +1,76 @@
+import { acquireLock, recoverAbandonedLock } from '../state/lock.js';
+import { createSnapshotStore, readSnapshotWithoutLock } from '../state/snapshot-store.js';
+import { verifyResolvedStatePaths } from '../state/paths.js';
+import { ensure, hash, plain, validateRecord } from './contract.js';
+const stores = new WeakSet();
+export function isDeliveryStore(value) {
+  return stores.has(value);
+}
+export function createDeliveryStore(paths, options = {}) {
+  const snapshots = createSnapshotStore(paths, options.snapshotOptions ?? {});
+  async function read() {
+    const snapshot = await readSnapshotWithoutLock(paths);
+    return snapshot === null ? null : plain({ ...validateRecord(snapshot.data), version: snapshot.version });
+  }
+  const store = Object.freeze({
+    read,
+    async recover() {
+      await verifyResolvedStatePaths(paths);
+      const operationPath = paths.operationLockPath ?? `${paths.snapshotPath}.operation.lock`;
+      const recoveredLocks = [];
+      if (await recoverAbandonedLock(operationPath, { now: options.recoveryNow })) recoveredLocks.push('operation');
+      const lock = await acquireLock(operationPath);
+      try {
+        await verifyResolvedStatePaths(paths);
+        if (await recoverAbandonedLock(paths.lockPath, { now: options.recoveryNow })) recoveredLocks.push('snapshot');
+        return plain({ recoveredLocks });
+      } finally {
+        await lock.release();
+      }
+    },
+    async write(input, { expectedVersion }) {
+      const value = validateRecord(input);
+      const prior = await read();
+      ensure((prior?.version ?? 0) === expectedVersion, 'version-conflict');
+      if (prior) {
+        ensure(
+          hash(prior.candidate) === hash(value.candidate) && value.createdAt === prior.createdAt,
+          'state-conflict'
+        );
+        ensure(
+          value.operations.length >= prior.operations.length &&
+            prior.usedApprovalIds.every((id) => value.usedApprovalIds.includes(id)),
+          'state-conflict'
+        );
+        for (let i = 0; i < prior.operations.length; i++) {
+          const old = prior.operations[i],
+            next = value.operations[i];
+          const { state: oldState, receipt: oldReceipt, ...oldBinding } = old;
+          const { state: nextState, receipt: nextReceipt, ...nextBinding } = next;
+          ensure(hash(oldBinding) === hash(nextBinding), 'state-conflict');
+          ensure(
+            oldState === 'dispatching' || oldState === 'indeterminate'
+              ? ['indeterminate', 'succeeded', 'not-applied'].includes(nextState)
+              : oldState === nextState,
+            'state-conflict'
+          );
+          if (old.state === 'succeeded' || old.state === 'not-applied')
+            ensure(hash(old) === hash(next), 'state-conflict');
+        }
+      }
+      const result = await snapshots.write(value, { expectedVersion, environment: {} });
+      return plain({ ...result.data, version: result.version });
+    },
+    async exclusive(operation) {
+      await verifyResolvedStatePaths(paths);
+      const lock = await acquireLock(paths.operationLockPath ?? `${paths.snapshotPath}.operation.lock`);
+      try {
+        return await operation();
+      } finally {
+        await lock.release();
+      }
+    },
+  });
+  stores.add(store);
+  return store;
+}

package/src/delivery/tracker-target.js

@@ -0,0 +1,51 @@
+import { validateWorkRequest } from '../work-request/contract.js';
+import { immutableJson } from '../clients/contract.js';
+import { DeliveryError } from './contract.js';
+
+const ISSUE_KEY = /^[A-Z][A-Z0-9]{0,31}-[1-9][0-9]{0,15}$/;
+function requireTarget(condition) {
+  if (!condition) throw new DeliveryError('tracker-target');
+}
+
+function issueUrl(value, kind, issueKey) {
+  requireTarget(typeof value === 'string' && value.length <= 2048);
+  const url = new URL(value);
+  requireTarget(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash);
+  const segments = url.pathname.split('/').filter(Boolean);
+  requireTarget(kind === 'jira'
+    ? segments.length === 2 && segments[0] === 'browse' && segments[1] === issueKey
+    : [3, 4].includes(segments.length) && segments[1] === 'issue' && segments[2] === issueKey);
+  return value;
+}
+
+/** Derive a tracker identity from the approved run; callers cannot supply a different ticket. */
+export function trackerTargetFromRun(run, candidate) {
+  try {
+    requireTarget(typeof run?.runId === 'string' && run.runId.length > 0 && run.runId === candidate?.runId);
+    // Snapshot source data before validation so the validated identity cannot change afterward.
+    const request = immutableJson(run.workRequest);
+    validateWorkRequest(request);
+    requireTarget(run.featurePlan?.workRequestDigest === request.digest);
+    let kind = request.source.kind;
+    let issueKey = request.source.ref;
+    let url = request.source.url;
+    if (kind === 'host-observation') {
+      const sources = request.context.sources;
+      const primary = sources[0];
+      const matches = sources.filter(source => `${source.providerId}:${source.resourceId}` === request.source.ref);
+      requireTarget(matches.length === 1 && matches[0] === primary);
+      requireTarget(request.source.revision === `sha256:${primary.contentDigest}` && url === primary.url);
+      requireTarget(primary.content.title === request.title && primary.content.description === request.description);
+      requireTarget(Array.isArray(primary.content.acceptanceCriteria));
+      const criteria = [...new Set([...primary.content.acceptanceCriteria, ...request.context.userAcceptanceCriteria])];
+      requireTarget(JSON.stringify(criteria) === JSON.stringify(request.acceptanceCriteria));
+      kind = primary.provider;
+      issueKey = primary.resourceId;
+      url = primary.url;
+    }
+    requireTarget(['jira', 'linear'].includes(kind) && typeof issueKey === 'string' && ISSUE_KEY.test(issueKey));
+    return Object.freeze({ kind, issueKey, issueUrl: issueUrl(url, kind, issueKey), requestDigest: request.digest });
+  } catch {
+    throw new DeliveryError('tracker-target');
+  }
+}