Run events - Pactmark

Compatibility: Pactmark 0.1.x. Every payload is a strict object. Events carry digests and ids — never prompt, completion, workspace or credential content.

States

Lifecycle

Event	Payload
`RunAccepted`	`workOrderId`, `workOrderBindingDigest`, `requiredVerifierIds[]`
`PlanningStarted`	`stepId`
`ExecutionStarted`	`stepId`, `toolCallId?`
`RunSuspended`	`stepId`, `resumeTarget`, `reasonCode`, `effectId?`
`RunCompleted`	`stepId`, `evidenceRecordId`, `outputDigest`
`RunFailed`	`stepId?`, `errorCode` (matching `/^KAF_[A-Z0-9_]+$/`), `safeDetails?`
`RunCancelled`	`stepId?`, `reasonCode`, `actorId`

resumeTarget is one of planning, running, verifying.

Model boundary

Event	Payload
`ModelCallStarted`	`stepId`, `modelCallReservationId`, `requestDigest`
`ModelCallCompleted`	`stepId`, `modelCallReservationId`, `responseDigest`, `finishReason`

Digests, not content. Reconstructing a prompt from a Pactmark event stream is impossible by design — which is also why the event stream is safe to retain longer than the model interaction itself.

Tools

Event	Payload
`ToolCallRequested`	`stepId`, `toolCallId`, `toolRegistrationDigest`, `argumentsDigest`
`ToolCallCompleted`	`stepId`, `toolCallId`, `resultDigest`

Retries

Event	Payload
`RetryScheduled`	`stepId`, `boundary` (`model`\|`tool`), `boundaryKey`, `attempt`, `nextAttempt`, `classification`, `delayMs`, `notBefore`
`RetryResumed`	`stepId`, `boundary`, `boundaryKey`, `attempt`

classification is timed_out, retryable or uncertain.

Human interaction

Event	Payload
`InputRequested`	`stepId`, `requestId`, `inputSchemaDigest`, `safePrompt`
`InputSubmitted`	`stepId`, `requestId`, `inputSubmissionRecordId`, `inputSchemaDigest`, `valueDigest`
`ApprovalRequested`	`stepId`, `decisionId`, `decisionGateDigest`, `proposedEffectDigest`
`ApprovalRecorded`	`stepId`, `decisionId`, `approvalId`, `resumeTarget` (`planning`\|`running`)
`ApprovalRejected`	`stepId`, `decisionId`, `nextStatus` (`planning`\|`failed`\|`cancelled`), `reasonCode`

safePrompt is a human-facing string, already separated from raw model output.

Effects

Event	Payload
`EffectPrepared`	`stepId`, `effectId`, `effectDigest`, `effectKey`, `strategy`
`EffectDispatched`	`stepId`, `effectId`, `attempt`
`EffectAcknowledged`	`stepId`, `effectId`, `resultDigest`, `acknowledgement`
`EffectUncertain`	`stepId`, `effectId`, `uncertaintyCode`
`EffectNeedsReconciliation`	`stepId`, `effectId`, `effectMayHaveOccurred: true`
`EffectReconciliationRecorded`	`stepId`, `effectId`, `resolution`, `commandId`
`EffectAbandoned`	`stepId`, `effectId`, `reason`, `effectMayHaveOccurred: true`
`CompensationRequested`	`stepId`, `originalRunId`, `originalEffectDigest`, `compensationRunId`
`EffectCompensated`	`stepId`, `originalEffectDigest`, `compensationEffectDigest`, `acknowledgementDigest`

effectMayHaveOccurred is a literal true on both EffectNeedsReconciliation and EffectAbandoned. The schema does not permit recording those states while implying the effect definitely did not happen.

resolution is recovered_acknowledgement or abandon_uncertain.

Output and verification

Event	Payload
`ArtifactProduced`	`stepId`, `artifactId`, `artifactDigest`
`VerificationStarted`	`stepId`, `artifactDigest`
`VerificationRecorded`	`stepId`, `verificationId`, `verifierId`, `status`, `verificationDigest`
`VerificationExceptionRecorded`	`stepId`, `exceptionId`, `exceptionDigest`, `verifierId`, `verifierRegistrationDigest`, `artifactDigest`, `rubricVersion`, `rubricDigest`, `reviewerRole`, `expiresAt`, `reason`, `compensatingControls[]`

status is pass, fail or needs_review. compensatingControls must be non-empty.

Consuming events

for await (const event of runtime.events(authority, runId, { afterSequence })) {
  switch (event.eventType) {
    case "ApprovalRequested":
      return queueForReview(event.payload.decisionId);
    case "EffectNeedsReconciliation":
      return alertOnCall(event.payload.effectId);
    case "RunFailed":
      return handle(event.payload.errorCode); // stable KAF_* code
  }
}

Branch on eventType and on KAF_* codes. Human-readable text, ordering outside the documented contract, and stack traces are not stable APIs.

Run lifecycle

How these events move the run between states.

Error reference

Every KAF_* code with its retryability and HTTP status.

​States

​Lifecycle

​Model boundary

​Tools

​Retries

​Human interaction

​Effects

​Output and verification

​Consuming events

Run lifecycle

Error reference

States

Lifecycle

Model boundary

Tools

Retries

Human interaction

Effects

Output and verification

Consuming events