reflect_apply

Category: reflection
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Applies accepted candidates from a completed run as conservative task mutations with snapshots. Call it after deciding; reruns are safe because applied candidates skip.

Arguments

Required: run_id.

Optional: applied_by, candidate_ids_csv.

run_id: id of a run in completed status. Other statuses error.
applied_by: actor recorded on each snapshot row. Note: Actor recorded on each snapshot; defaults user.
candidate_ids_csv: optional comma-separated subset of candidate ids to apply. Empty string = apply all accepted.

Result

Object with run_id, considered and applied counts, skipped array (candidate_id plus reason), and failed array (candidate_id plus error).

Boundaries

Run must be completed and its input project granted (unfiltered runs are star-only; foreign runs read as not-found, never leaking status). Every task target re-checks caller scope before mutation; denied targets land in skipped as target_out_of_scope.

Lifecycle / side effects

Applies accepted candidates through the canonical task mutation path with before/after snapshots per candidate. Already-applied candidates skip idempotently as already_applied; entity targets skip (no archive primitive yet); vanished targets skip as target_not_found. All-or-nothing per call.

Errors

Unknown, discarded, or foreign runs read as not-found; non-completed runs fail as run_not_completed. Engine failures return normal error plus internal_error payloads, never transport errors.

Example

{
  "run_id": "<uuid>"
}

Result shape:

{
  "applied": 2,
  "considered": 3,
  "failed": [],
  "run_id": "<uuid>",
  "skipped": [
    {
      "candidate_id": "<uuid>",
      "reason": "already_applied"
    }
  ]
}