Cache optimization and convergence

Optimize workflow caches and follow convergence from preparation through verification and promotion. Learn how to interpret blockers, proof runs, partial promotion, and review-gated outcomes.

Cache optimization helps you improve a flow’s cache behavior while preserving evidence of how Cofactor reached its result. Start an optimization run, follow each convergence phase, review proof-run information and blockers, and decide whether the result is ready for promotion.

01When to use cache optimization

Use cache optimization when a flow needs faster or more reliable reuse of previously established state. Optimization is useful when you want to validate a cache recipe against real interaction behavior before promoting changes broadly.

Start an optimization when you need to:

Prepare a flow for cache convergence without changing the active behavior immediately.
Track whether the run is preparing, converging, verifying, or ready for promotion.
Investigate why a result is blocked, partially promoted, or waiting for review.
Compare the optimization result with proof-run evidence before you promote it.

Run optimization against a stable flow with representative data and interactions. Resolve flow or environment problems first so that convergence results reflect cache behavior rather than unrelated failures.

02Core concepts

Optimization runs

An optimization run is the complete record of a cache-convergence attempt for a flow. It includes the run status, phase timing, convergence details, verification results, blockers, proof-run information, and promotion outcome.

Optimization runs appear in the flow’s Runs tab. Open a run to view its detailed drawer and inspect what happened at each stage. Use the drawer to distinguish an active run from a terminal result and to find the evidence needed before taking action.

An optimization run can end with a full promotion, a partial promotion, or a review-gated result. A run may also remain blocked when Cofactor cannot verify the conditions required to promote the result.

Convergence phases

Follow the run through these phases:

Phase	What to look for
Preparation	Cofactor validates the flow and prepares the optimization run. Address preparation blockers before expecting convergence to begin.
Convergence	Cofactor exercises the flow and works toward a stable cache result. Watch the run timing and current status while this phase is active.
Verification	Cofactor checks the result against the available assertions and proof-run evidence. Review any assertion or evidence warnings before promotion.
Promotion	Cofactor applies the verified result, or reports why promotion is partial or requires review.

Phase timing helps you identify where a run is spending time and whether a delay is part of normal convergence or a sign of a blocker. Wait for a phase to finish before treating its status as final.

Proof runs and verification

Proof runs provide supporting evidence for verification. Cofactor can use clean prior runs as verifier proof when they satisfy the conditions for the optimization, so a previously successful run can help confirm that the proposed cache result is safe to promote.

Review the proof-run details in the optimization run drawer. Confirm that the proof run represents the intended flow behavior, then check verification findings, assertions, and any warnings. Assertion-tolerant checks can reduce unnecessary blocking when a check does not prevent the cache result from being safely evaluated, but review the resulting evidence before promotion.

03Start and monitor an optimization

Open the flow you want to optimize and confirm that its cache configuration and interactions are ready to exercise.
Start cache optimization for the flow. Cofactor creates an optimization run and begins the preparation phase.
Open the flow’s Runs tab and locate the new convergence run.
Open the run drawer to monitor the current phase, elapsed timing, verification state, proof-run information, and blockers.
Wait for the run to reach a terminal outcome. Refresh the run view when you need to check progress, and use the latest drawer details to decide whether action is required.
If the run is blocked, follow each blocker to the affected flow behavior or verification condition. Correct the issue, then start another optimization run.

Starting at a fork can begin deterministic optimization earlier when the flow supports it. Use that option when you need repeatable convergence behavior and have a stable starting point.

04Review blockers and promotion outcomes

Treat the run outcome as a decision about what to do next, not just as a pass or fail. Open the detailed run drawer and review every blocker, warning, proof-run reference, and verification result before promoting or rerunning.

Full promotion

A full promotion means the verified optimization result is ready to apply across the intended cache scope. Confirm the verification evidence and timing, then use the available promotion action in the run details.

After promotion, run the flow again when you need to confirm the promoted behavior in its normal workflow. Keep the optimization run as the record of the evidence and decision.

Partial promotion

A partial promotion means Cofactor verified and promoted only the portion of the result that met the required conditions. Review which parts were promoted and which remain unresolved in the run drawer.

Use the unresolved blockers to guide the next optimization. Do not assume that a partial result covers the entire flow; validate the affected interactions and rerun optimization after addressing the remaining issues.

Review-gated results

A review-gated result means Cofactor has produced useful optimization and verification information, but the result needs a person to review it before promotion. This outcome can occur when evidence is incomplete, checks need interpretation, or the result does not meet every automatic promotion condition.

Review the proof-run information, verification findings, assertion evidence, timing, and blockers. Promote only after you confirm that the result matches the intended flow behavior. If the evidence is insufficient, resolve the underlying issue and start a new run instead.

05Best practices

Start with a stable, representative flow and reliable test data.
Review the full run drawer instead of relying only on the terminal status.
Use clean prior runs as proof only when they represent the same intended behavior.
Investigate preparation and verification blockers before rerunning repeatedly.
Treat partial promotion as a scope-limited result and document what remains unpromoted.
Use review-gated outcomes for deliberate human verification, not as a substitute for missing evidence.
Compare phase timing across runs to identify unstable setup, convergence, or verification behavior.
Keep the optimization run associated with the flow so later reviewers can trace the promotion decision.

Cache authoring — Configure and refine the cache behavior used by a flow.
Runs — Review flow runs, statuses, timing, and evidence.
Diagnostics — Investigate failures and collect supporting evidence when optimization is blocked.