Where a framework or a system meets the boundary

/**
 * The interface every native executor implements. The runner calls it in one
 * order: `capabilities` and `prepare` at admission, `execute` once after the
 * claim (dispatch) or at presentation (permit), `observe` on the platform's
 * answer, and `reconcile` only after an indeterminate observation or a
 * missing receipt.
 */
export interface NativeExecutor<TAction = unknown, TReceipt = JsonObject, TResult = unknown> {
  readonly platform: PlatformId;
  readonly version: string;
  readonly style: ExecutionStyle;
  readonly actionTypes: readonly ActionType[];
  /** What can be executed now, and what is missing when it cannot (scope, switch, connection). */
  capabilities(scope: ExecutorScope): Promise<readonly ExecutionCapability[]>;
  /** Platform facts + `agent-safe.intent/1` binding + idempotency identity. No I/O side effects. */
  prepare(action: TAction, scope: ExecutorScope | null): Promise<PreparedAction>;
  /**
   * Optional: the target's state version, read once, read-only, after
   * `prepare` and before the authority is asked. The runner binds it into the
   * intent as `agent_safe.precondition`; the authority carries it to a
   * verifying provider, which refuses the write once the target moved on, and
   * an executor whose platform takes a conditional write sends it as the
   * write's precondition (`If-Match`) itself. Null when the action names no
   * existing target, a create. It is the only I/O before a decision, and a
   * read that fails is a refusal: nothing is decided without the version the
   * executor said it would bind.
   */
  readState?(
    action: TAction,
    prepared: PreparedAction,
    scope: ExecutorScope | null,
  ): Promise<TargetPrecondition | null>;
  /** dispatch: write once with the claimed grant. permit: return the permit the native boundary must present. */
  execute(run: ClaimedExecution<TAction>): Promise<ExecutionEffect<TReceipt>>;
  /** Map the native receipt (posting entry, feed ID, HTTP status) to COMMITTED | FAILED | INDETERMINATE. */
  observe(
    effect: ExecutionEffect<TReceipt>,
    prepared: PreparedAction,
  ): Promise<EffectObservation<TResult>>;
  /** Called only after INDETERMINATE or a missing receipt: COMPLETED | NOT_EXECUTED | UNKNOWN. */
  reconcile(context: ReconcileContext): Promise<ReconcileResult<TResult>>;
}

packages/pipeline/src/execution/NativeExecutor.ts at v0.5.0. View the file