Finite Lifecycles

A finite lifecycle models work with a known sequence of stages. At each stage, the agent receives new evidence and submits a result before it can continue. The host checks that the submission has the required structure; the task verifier separately checks whether it is correct.

Use a lifecycle when the stage order and completion conditions are known before execution. Use an Interactive World when actor actions change an ongoing causal state. Use an artefact task when one workspace or submission is enough.

Who controls each part

The task owns stage meaning. The lifecycle host owns progression.

One stage is active at a time. A structurally invalid result leaves the current stage and earlier submissions unchanged. The host archives a structurally valid result and activates the next stage; the task verifier separately determines correctness.

The host marks the lifecycle complete only after it archives the terminal result.

What a lifecycle defines

EvidenceLifecycleSpec defines an ordered evidence workflow. Each checkpoint names:

• its instruction;
• the evidence release visible at that stage;
• the expected submission path;
• any earlier checkpoint that must already be accepted; and
• the required submission fields.

The materialize command creates a portable folder with the stage instructions, evidence, and submission locations. The host checks submission structure; the task verifier defines task-specific correctness.

Lifecycle identity is separate from task status. proposed, active, deprecated, and retired describe catalogue status. Lifecycle checkpoints describe evidence progression during one run.

Create and inspect a package

List the installed lifecycle tasks:

aec-bench task lifecycle list

Create one package and run the deterministic smoke actor:

aec-bench task lifecycle materialize hydraulic-design-response-lifecycle-review \
  --output artefacts/lifecycles/hydraulic-review

aec-bench task lifecycle run-smoke artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review-smoke

aec-bench task lifecycle verify artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review-smoke

run-smoke checks the local package and stage progression with a deterministic actor. Use a model-backed run to test a hosted provider.

Some lifecycle families expose public semantic variants. Inspect them before materialisation:

aec-bench task lifecycle list-variants hydraulic-interaction-lifecycle-review
aec-bench task lifecycle materialize hydraulic-interaction-lifecycle-review \
  --variant tailwater_revision \
  --output artefacts/lifecycles/hydraulic-review-tailwater

Control a lifecycle run

All lifecycle host controls are under aec-bench task lifecycle:

aec-bench task lifecycle start \
  --package artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review

aec-bench task lifecycle status \
  --package artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review

aec-bench task lifecycle submit \
  --package artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review

start creates a run when required and releases its next checkpoint. The actor must write the required submission before submit archives it. status reads the current state without advancing it.

Revisit an accepted checkpoint without changing the active checkpoint:

aec-bench task lifecycle revisit \
  --package artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review \
  --checkpoint-id checkpoint-1 \
  --reason "Review the accepted evidence"

Create a derived run from a submitted checkpoint:

aec-bench task lifecycle branch \
  --package artefacts/lifecycles/hydraulic-review \
  --parent-run-dir artefacts/lifecycle-runs/hydraulic-review \
  --branch-run-dir artefacts/lifecycle-runs/hydraulic-review-alternative \
  --checkpoint-id checkpoint-2 \
  --branch-id alternative-review \
  --reason "Test a different decision"

A branch receives the accepted prefix through the selected checkpoint, reopens that checkpoint, and leaves its parent unchanged. The host rejects an unsubmitted branch point. There is no start_at option that bypasses the accepted history.

Run or resume the lifecycle with a local agent harness:

aec-bench task lifecycle run \
  --package artefacts/lifecycles/hydraulic-review \
  --run-dir artefacts/lifecycle-runs/hydraulic-review \
  --model gpt-4.1-mini \
  --mode persistent_context

Use --mode fresh_context to create a separate agent session for each checkpoint attempt. Persistent context keeps one session across checkpoints. These modes are distinct treatments with different memory and recovery rules.

Python API

Python callers can control checkpoints through direct functions:

from aec_bench.lifecycles.application import (
    branch_lifecycle,
    read_lifecycle,
    release_checkpoint,
    revisit_checkpoint,
    run_lifecycle,
    submit_checkpoint,
)

These functions use the same lifecycle rules as the CLI. read_lifecycle() returns the current authoritative state. revisit_checkpoint() only reads an accepted stage. branch_lifecycle() creates a separate run from accepted work, and run_lifecycle() continues from the current state with a fresh agent context.

Lifecycle execution and trial composition use ordinary in-memory values:

from aec_bench.harness.lifecycle_local import run_local_lifecycle
from aec_bench.lifecycles.application import (
    LifecycleExecution,
    LifecycleTrial,
    run_lifecycle_experiment,
    run_lifecycle_trial,
)

record = run_lifecycle_trial(
    trial=lifecycle_trial,
    execute=run_local_lifecycle,
    verify=verify_lifecycle,
)

LifecycleTrial binds one PlannedTrial to its materialised package, run directory, execution mode, and visibility policy. run_local_lifecycle() keeps the fresh-session and persistent-session implementations separate and returns LifecycleExecution evidence.

run_lifecycle_trial() executes, verifies, builds, and returns one normal TrialRecord. It persists the record only when the caller supplies a persistence function. run_lifecycle_experiment() applies the same operation to planned trials in declared order and returns their TrialRecord values directly.

Lifecycle studies

Lifecycle-specific study policy remains under the lifecycle command group:

aec-bench task lifecycle study ablation --config lifecycle-ablation.yaml --dry-run
aec-bench task lifecycle study calibration-freeze --config lifecycle-ablation.yaml

Ablation uses the common lifecycle trial and experiment functions. It retains its study-specific planning, immutable snapshots, recovery, and selection policy. A lifecycle evaluator supplies completed records to meta-harness studies.

Conditional work

A checkpoint can declare a bounded set of conditional operations. The actor chooses from task-owned operations, but the host enforces the operation budget and prerequisites.

Conditional evidence requests remain an experimental staged-evidence capability. Current registered workflows use fixed evidence releases or conditional operations.

Choose either conditional evidence requests or conditional operations within one lifecycle in the current host implementation.

What the run records

The execution record keeps the model, agent harness, context mode, status, usage, and retained files needed to understand the run. The final TrialRecord links to this evidence. The lifecycle's own execution record remains the source of truth for stage state.

Persistent-context and fresh-context execution are explicit choices. Fresh sessions can receive only the evidence allowed by their memory visibility policy. The resolved model and agent harness stay stable across one lifecycle execution.

Prime Lab can export a registered public lifecycle variant as a local-only Prime package:

aec-bench prime export-lifecycle \
  --name hydraulic-review \
  --package artefacts/lifecycles/hydraulic-review-tailwater \
  --output-dir prime-rl/environments \
  --aec-bench-root /absolute/path/to/aec-bench

The generated package keeps absolute references to the materialised lifecycle and an editable local AEC-Bench checkout. It supports local evaluation. Continual-learning or transfer claims require a separate study and evidence path.

See Prime Lab for package and hosted-evaluation limits, and Review and Reporting for evidence interpretation.