# Decisions and execution

Klineo separates private decision review from custody-changing proposals. A Decision Pack records evidence and a human decision. An executable proposal binds a specific vault action to policy, simulation, snapshot, nonce, and transaction checks. Approving a review artifact does not grant financial authority.

## Decision Packs

A Decision Pack is a versioned workspace artifact. Its supported sources include public project and Health evidence, private Research candidates, and historical treasury scenario projections. Source bindings preserve the saved evidence generation instead of asserting that a historical observation remains current.

The lifecycle is `DRAFT`, `READY_FOR_REVIEW`, `DECISION_RECORDED`, `FOLLOW_UP_DUE`, `CLOSED`, or `SUPERSEDED`. A human can record `DO_NOTHING`, `REQUEST_MORE_EVIDENCE`, or `TAKE_TO_SEPARATE_APPROVAL`, together with rationale. The last choice requests progression to another workflow; it does not approve a Safe transaction.

Public-evidence assumptions are human notes, not verified facts or executable simulation inputs. A supporting Health investigation can answer a different question from the pack's question. Research candidates retain exact private trial references and a selected capital variant across scenarios; eligible candidate Review receipts can attach without changing financial authority. Treasury packs bind declared historical assumptions and saved projections, rather than certifying current cash balances. Commercial-order references remain unsupported.

Use the pack to gather the relevant evidence, review the exact saved sources, and record the decision. Follow-up due is an explicit recorded transition, not an automatic reminder or monitoring instruction. Closing a pack saves a human note; it does not create a finalized Outcome Ledger report.

Writes require the authorized workspace actor, an idempotency key, and the reviewed strong `If-Match` resource version. History remains immutable. Reload after a stale-version rejection; retry an uncertain request using its original payload and key. A historical version is for inspection and does not accept new commands.

## Vault operating modes

| Mode | Behavior |
| --- | --- |
| `OBSERVE` | Observe evidence; the shadow lifecycle can record decisions and simulations with the send path suppressed |
| `RECOMMEND` | Prepare proposals for separate issuer review and Safe execution |
| `BOUNDED_EXECUTE` | Allow the operated scheduler and configured executor to act inside issuer-authorized policy and live release gates |
| `EMERGENCY` | Pause normal strategy operation and use the separately authorized control or reduction paths |

Modes are distinct from the vault lifecycle. A live proposal ordinarily requires `LIVE_CAPPED` or `LIVE_EXPANDED`. Predeployment shadow decisions require an independently approved policy bound to the selected canonical simulation. Shadow records retain their evidence but remove executable envelope authority.

Diversify requires issuer-Safe approval and cannot enter the unattended bounded executor queue. Native BOT wrap and WBOT unwrap are also issuer-Safe-only; they require the WBOT quote profile. Unwrap delivery is bound to the immutable issuer Safe.

## Proposal admission

The normal proposal path progresses through input validation, strategy computation, policy evaluation, and exact transaction simulation. A policy rejection or simulation failure records the reason and prevents progression.

An action envelope binds:

- Vault address, chain ID, and action nonce.
- Active onchain policy hash and strategy version.
- Input snapshot, simulation, and action hashes.
- Creation time and deadline.
- Expected pre-action NAV, minimum post-action NAV, and maximum gas reimbursement.

The backend derives typed controller calldata from these values. Its initial preflight executes the exact transaction against the finalized snapshot's block number and hash, with the bound sender, target, value, and runtime evidence. A Digital Twin result or successful local policy calculation cannot substitute for this transaction simulation.

Before admission, the service also checks current simulation-to-vault and policy bindings, executable snapshot freshness, dependency eligibility, safety authority, and applicable commercial authority. A changed policy, paused control state, expired deadline, revoked dependency, or missing runtime evidence can stop progression even when an earlier study succeeded.

## Manual approval and Safe handoff

In `RECOMMEND` mode, a successfully simulated proposal becomes `APPROVAL_PENDING`. An authorized second actor must approve the reviewed proposal generation; its immutable creator cannot approve their own proposal. The approval records actor, role, time, and reason and moves the proposal to `READY`.

Workspace approval is followed by the issuer's Safe workflow. Creating the Safe bundle requires a ready proposal with its action, envelope, nonce, and transaction-simulation evidence. The service rechecks live mode, lifecycle, deadline, source and safety authority, and performs current-state preflight before producing the exact packet. Safe signers review and execute it using their own signing authority.

If a packet is rejected or expires, review current evidence before preparing a new proposal. Treat a changed transaction's calldata, destination, value, policy, or nonce as a different authority to review.

## Bounded execution

In an issuer-authorized `BOUNDED_EXECUTE` mode, a successfully admitted proposal can move through `AUTO_AUTHORIZED` to `READY`. Arbitrary workspace users cannot choose unattended keeper timing; the operated scheduler principal prepares that work.

The execution coordinator must acquire a current fenced lease and recheck live lifecycle, mode, snapshot, safety admission, dependency eligibility, commercial authority, deadline, sender binding, and current transaction preflight. It submits the immutable controller transaction through the configured gateway. After an ambiguous or interrupted submission, recovery looks up the original durable gateway claim before attempting nonce-sensitive work.

These mechanisms support consistent submission and recovery. They do not guarantee inclusion, price outcomes, availability of a signing service, or absence of chain failure.

## Controller checks and protected authority

The onchain controller checks the envelope digest, action hash, policy version, deadline, sender authority, pause state, and proposal/nonce consumption. Typed adapters constrain supported position and swap operations. Normal value-protected actions authenticate live custody NAV and source health before and after execution. Position ranges, reserves, turnover, realized loss, cooldown, daily actions, and gas reimbursement remain subject to policy limits.

The controller anchors the post-action value floor to authenticated live NAV and policy, in addition to the envelope's claimed values. Exceeding an atomic policy invariant reverts the transaction and its dependent vault mutations. Normal executor and Safe actions consume the common action and cooldown budgets; guardian emergency reduction is a separate authenticated path.

Issuer pause, withdrawal, and exit authority is separate from routine proposal approval. Guardian and issuer control operations have their own role and command checks. An emergency path should be reviewed as the exact operation it authorizes rather than treated as permission to perform a normal strategy action.

## From submission to outcome

Follow the recorded states after submission: `SUBMITTED`, possible `REPLACED`, `INCLUDED`, `FINALIZED`, `RECONCILED`, and `ATTRIBUTED`. Inclusion is not finality; finality is not successful reconciliation. Failed execution and reconciliation remain visible with their evidence.

Reconciliation checks the actual transaction and receipt, controller action, nonce, amounts, and finalized custody observation. Attribution records costs and supported outcome measurements. An outer Safe failure can leave the controller nonce unconsumed; a separately registered later exact attempt may succeed, while the failed receipt still contributes reportable cost evidence. Use the selected reconciled economic outcome and attempt history together.

## Release availability

The documented paths describe implemented software and contract checks. The checked-in canonical v1 and v2 manifests currently set activation to false; v2 also disables automated execution and live rollout. A disposable testnet sandbox is separate from canonical production authority. A successful build, SDK call, study, or contract test does not enable funding or live execution. Inspect the running environment's release and capability status before using a custody-changing workflow.