# planning
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

Markdown source of https://develop.atlas-kit-docs.pages.dev/reference/planning/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="assemblypolicy"></a>

### AssemblyPolicy

Defined in: [packages/sage/src/planning/assembly.ts:52](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L52)

Policy for assembling an unsigned transaction from one Plan.

Transaction-exclusive Plans reject `computeUnitLimit` and
`priorityFeeMicroLamports` because either field adds another instruction.

#### Example

```ts
declare const feePayer: Address;
const policy: AssemblyPolicy = { feePayer, computeUnitLimit: 400_000 };
```

#### Properties

<a id="commitment"></a>

##### commitment?

```ts
readonly optional commitment?: Commitment;
```

Defined in: [packages/sage/src/planning/assembly.ts:56](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L56)

<a id="computeunitlimit"></a>

##### computeUnitLimit?

```ts
readonly optional computeUnitLimit?: number;
```

Defined in: [packages/sage/src/planning/assembly.ts:54](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L54)

<a id="feepayer"></a>

##### feePayer

```ts
readonly feePayer: Address;
```

Defined in: [packages/sage/src/planning/assembly.ts:53](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L53)

<a id="priorityfeemicrolamports"></a>

##### priorityFeeMicroLamports?

```ts
readonly optional priorityFeeMicroLamports?: bigint;
```

Defined in: [packages/sage/src/planning/assembly.ts:55](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L55)

***

<a id="confirmedplanexecution"></a>

### ConfirmedPlanExecution

Defined in: [packages/sage/src/planning/execution.ts:74](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L74)

A transaction confirmed at the requested commitment.

#### Example

```ts
declare const result: ConfirmedPlanExecution;
console.log(result.signature, result.slot);
```

#### Properties

<a id="commitment-1"></a>

##### commitment

```ts
readonly commitment: Commitment;
```

Defined in: [packages/sage/src/planning/execution.ts:78](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L78)

<a id="signature"></a>

##### signature

```ts
readonly signature: Signature;
```

Defined in: [packages/sage/src/planning/execution.ts:76](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L76)

<a id="slot"></a>

##### slot

```ts
readonly slot: bigint;
```

Defined in: [packages/sage/src/planning/execution.ts:77](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L77)

<a id="status"></a>

##### status

```ts
readonly status: "confirmed";
```

Defined in: [packages/sage/src/planning/execution.ts:75](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L75)

***

<a id="createplaninput"></a>

### CreatePlanInput

Defined in: [packages/sage/src/planning/index.ts:230](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L230)

Caller-owned fields accepted by the Plan factory.

`affected` and `requiredSigners` are intentionally absent because the
factory derives them from writable metas and ordered step signers.

#### Example

```ts
declare const step: PlanStep;
const input: CreatePlanInput = {
  kind: 'fleet.move',
  summary: 'Move the fleet.',
  steps: [step],
  preconditions: [],
};
```

#### Properties

<a id="kind"></a>

##### kind

```ts
readonly kind: string;
```

Defined in: [packages/sage/src/planning/index.ts:231](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L231)

<a id="preconditions"></a>

##### preconditions

```ts
readonly preconditions: readonly PlanPrecondition[];
```

Defined in: [packages/sage/src/planning/index.ts:234](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L234)

<a id="steps"></a>

##### steps

```ts
readonly steps: readonly PlanStep[];
```

Defined in: [packages/sage/src/planning/index.ts:233](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L233)

<a id="summary"></a>

##### summary

```ts
readonly summary: string;
```

Defined in: [packages/sage/src/planning/index.ts:232](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L232)

***

<a id="createplansequenceinput"></a>

### CreatePlanSequenceInput

Defined in: [packages/sage/src/planning/plan-sequence.ts:111](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L111)

Exact caller-owned input accepted by `createPlanSequence`.

#### Example

```ts
declare const step: PlanSequenceStep;
const input: CreatePlanSequenceInput = {
  cluster: 'zink-ptr',
  sequenceId: 'fleet-round-trip',
  revision: 0,
  steps: [step],
};
```

#### Properties

<a id="cluster"></a>

##### cluster

```ts
readonly cluster: ClusterIdentity;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:112](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L112)

<a id="revision"></a>

##### revision

```ts
readonly revision: number;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:114](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L114)

<a id="sequenceid"></a>

##### sequenceId

```ts
readonly sequenceId: string;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:113](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L113)

<a id="steps-1"></a>

##### steps

```ts
readonly steps: readonly PlanSequenceStep[];
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:115](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L115)

***

<a id="executeplanoptions"></a>

### ExecutePlanOptions

Defined in: [packages/sage/src/planning/execution.ts:56](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L56)

Options for signing, submitting, confirming, and reconciling one Plan.

#### Example

```ts
import type { TransactionSigner } from '@solana/kit';

declare const feePayer: TransactionSigner;
const options: ExecutePlanOptions = { feePayer };
```

#### Properties

<a id="commitment-2"></a>

##### commitment?

```ts
readonly optional commitment?: Commitment;
```

Defined in: [packages/sage/src/planning/execution.ts:61](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L61)

<a id="computeunitlimit-1"></a>

##### computeUnitLimit?

```ts
readonly optional computeUnitLimit?: number;
```

Defined in: [packages/sage/src/planning/execution.ts:59](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L59)

<a id="feepayer-1"></a>

##### feePayer

```ts
readonly feePayer: TransactionSigner;
```

Defined in: [packages/sage/src/planning/execution.ts:57](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L57)

<a id="pollintervalms"></a>

##### pollIntervalMs?

```ts
readonly optional pollIntervalMs?: number;
```

Defined in: [packages/sage/src/planning/execution.ts:63](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L63)

<a id="priorityfeemicrolamports-1"></a>

##### priorityFeeMicroLamports?

```ts
readonly optional priorityFeeMicroLamports?: bigint;
```

Defined in: [packages/sage/src/planning/execution.ts:60](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L60)

<a id="signers"></a>

##### signers?

```ts
readonly optional signers?: readonly TransactionSigner[];
```

Defined in: [packages/sage/src/planning/execution.ts:58](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L58)

<a id="timeoutms"></a>

##### timeoutMs?

```ts
readonly optional timeoutMs?: number;
```

Defined in: [packages/sage/src/planning/execution.ts:62](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L62)

***

<a id="executeplansequenceoptions"></a>

### ExecutePlanSequenceOptions

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:74](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L74)

Inputs for one fail-closed PlanSequence execution or resume invocation.

The commitment is restricted to rollback-safe `confirmed` or `finalized`
evidence. Cancellation is observed only between steps.

#### Example

```ts
declare const feePayer: ExecutePlanSequenceOptions['feePayer'];
declare const store: PlanSequenceStore;
const options: ExecutePlanSequenceOptions = { feePayer, store };
```

#### Extends

- `Omit`\<[`ExecutePlanOptions`](/reference/planning/#executeplanoptions), `"commitment"`\>

#### Properties

<a id="commitment-3"></a>

##### commitment?

```ts
readonly optional commitment?: "confirmed" | "finalized";
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:78](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L78)

<a id="computeunitlimit-2"></a>

##### computeUnitLimit?

```ts
readonly optional computeUnitLimit?: number;
```

Defined in: [packages/sage/src/planning/execution.ts:59](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L59)

###### Inherited from

[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`computeUnitLimit`](/reference/planning/#executeplanoptions)

<a id="feepayer-2"></a>

##### feePayer

```ts
readonly feePayer: TransactionSigner;
```

Defined in: [packages/sage/src/planning/execution.ts:57](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L57)

###### Inherited from

[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`feePayer`](/reference/planning/#executeplanoptions)

<a id="onbeforesign"></a>

##### onBeforeSign?

```ts
readonly optional onBeforeSign?: (presentation) => Promise<void>;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:81](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L81)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `presentation` | [`PlanSequencePresentation`](/reference/planning/#plansequencepresentation) |

###### Returns

`Promise`\<`void`\>

<a id="pollintervalms-1"></a>

##### pollIntervalMs?

```ts
readonly optional pollIntervalMs?: number;
```

Defined in: [packages/sage/src/planning/execution.ts:63](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L63)

###### Inherited from

[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`pollIntervalMs`](/reference/planning/#executeplanoptions)

<a id="priorityfeemicrolamports-2"></a>

##### priorityFeeMicroLamports?

```ts
readonly optional priorityFeeMicroLamports?: bigint;
```

Defined in: [packages/sage/src/planning/execution.ts:60](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L60)

###### Inherited from

[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`priorityFeeMicroLamports`](/reference/planning/#executeplanoptions)

<a id="signal"></a>

##### signal?

```ts
readonly optional signal?: AbortSignal;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:80](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L80)

<a id="signers-1"></a>

##### signers?

```ts
readonly optional signers?: readonly TransactionSigner[];
```

Defined in: [packages/sage/src/planning/execution.ts:58](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L58)

###### Inherited from

[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`signers`](/reference/planning/#executeplanoptions)

<a id="store"></a>

##### store

```ts
readonly store: PlanSequenceStore;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:79](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L79)

<a id="timeoutms-1"></a>

##### timeoutMs?

```ts
readonly optional timeoutMs?: number;
```

Defined in: [packages/sage/src/planning/execution.ts:62](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L62)

###### Inherited from

[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`timeoutMs`](/reference/planning/#executeplanoptions)

***

<a id="plan"></a>

### Plan

Defined in: [packages/sage/src/planning/index.ts:202](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L202)

Inert, inspectable action data built only through planning factories.

#### Example

```ts
declare const plan: Plan;
console.log(plan.summary);
console.log(plan.describe());
```

#### Properties

<a id="plan_brand"></a>

##### \[PLAN\_BRAND\]

```ts
readonly [PLAN_BRAND]: true;
```

Defined in: [packages/sage/src/planning/index.ts:211](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L211)

<a id="affected"></a>

##### affected

```ts
readonly affected: readonly Address[];
```

Defined in: [packages/sage/src/planning/index.ts:207](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L207)

<a id="kind-1"></a>

##### kind

```ts
readonly kind: string;
```

Defined in: [packages/sage/src/planning/index.ts:203](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L203)

<a id="preconditions-1"></a>

##### preconditions

```ts
readonly preconditions: readonly PlanPrecondition[];
```

Defined in: [packages/sage/src/planning/index.ts:206](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L206)

<a id="requiredsigners"></a>

##### requiredSigners

```ts
readonly requiredSigners: readonly Address[];
```

Defined in: [packages/sage/src/planning/index.ts:208](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L208)

<a id="steps-2"></a>

##### steps

```ts
readonly steps: readonly PlanStep[];
```

Defined in: [packages/sage/src/planning/index.ts:205](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L205)

<a id="summary-1"></a>

##### summary

```ts
readonly summary: string;
```

Defined in: [packages/sage/src/planning/index.ts:204](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L204)

#### Methods

<a id="describe"></a>

##### describe()

```ts
describe(): readonly string[];
```

Defined in: [packages/sage/src/planning/index.ts:209](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L209)

###### Returns

readonly `string`[]

<a id="tojson"></a>

##### toJSON()

```ts
toJSON(): 
  | PlanJsonV1
  | PlanJsonV2;
```

Defined in: [packages/sage/src/planning/index.ts:210](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L210)

###### Returns

  \| [`PlanJsonV1`](/reference/planning/#planjsonv1)
  \| [`PlanJsonV2`](/reference/planning/#planjsonv2)

***

<a id="planjsonv1"></a>

### PlanJsonV1

Defined in: [packages/sage/src/planning/index.ts:113](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L113)

The complete persistent wire representation of a Plan.

#### Example

```ts
declare const wire: PlanJsonV1;
console.log(wire.v); // 1
```

#### Properties

<a id="affected-1"></a>

##### affected

```ts
readonly affected: readonly string[];
```

Defined in: [packages/sage/src/planning/index.ts:136](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L136)

<a id="kind-2"></a>

##### kind

```ts
readonly kind: string;
```

Defined in: [packages/sage/src/planning/index.ts:115](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L115)

<a id="preconditions-2"></a>

##### preconditions

```ts
readonly preconditions: readonly {
  address: string;
  dataHash: string;
  describes: string;
  kind: "account-state";
}[];
```

Defined in: [packages/sage/src/planning/index.ts:130](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L130)

<a id="requiredsigners-1"></a>

##### requiredSigners

```ts
readonly requiredSigners: readonly string[];
```

Defined in: [packages/sage/src/planning/index.ts:137](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L137)

<a id="steps-3"></a>

##### steps

```ts
readonly steps: readonly {
  describes: string;
  instruction: {
     accounts?: readonly {
        address: string;
        role: AccountRole;
     }[];
     data?: string;
     programAddress: string;
  };
  signers: readonly string[];
}[];
```

Defined in: [packages/sage/src/planning/index.ts:117](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L117)

<a id="summary-2"></a>

##### summary

```ts
readonly summary: string;
```

Defined in: [packages/sage/src/planning/index.ts:116](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L116)

<a id="v"></a>

##### v

```ts
readonly v: 1;
```

Defined in: [packages/sage/src/planning/index.ts:114](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L114)

***

<a id="planjsonv2"></a>

### PlanJsonV2

Defined in: [packages/sage/src/planning/index.ts:158](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L158)

The version-two Plan wire representation for semantic facts or account absence.

Version two retains every version-one top-level field and adds optional
normalized semantic facts to individual steps plus account-absence
preconditions. A Plan emits version two when either feature is present.

#### Example

```ts
declare const plan: Plan;
const wire: PlanJsonV1 | PlanJsonV2 = plan.toJSON();
if (wire.v === 2) {
  const absent = wire.preconditions.find(
    (precondition) => precondition.kind === 'account-absent',
  );
  console.log(wire.steps[0]?.semantics, absent?.address);
}
```

#### Properties

<a id="affected-2"></a>

##### affected

```ts
readonly affected: readonly string[];
```

Defined in: [packages/sage/src/planning/index.ts:189](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L189)

<a id="kind-3"></a>

##### kind

```ts
readonly kind: string;
```

Defined in: [packages/sage/src/planning/index.ts:160](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L160)

<a id="preconditions-3"></a>

##### preconditions

```ts
readonly preconditions: readonly (
  | {
  address: string;
  dataHash: string;
  describes: string;
  kind: "account-state";
}
  | {
  address: string;
  describes: string;
  kind: "account-absent";
})[];
```

Defined in: [packages/sage/src/planning/index.ts:176](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L176)

<a id="requiredsigners-2"></a>

##### requiredSigners

```ts
readonly requiredSigners: readonly string[];
```

Defined in: [packages/sage/src/planning/index.ts:190](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L190)

<a id="steps-4"></a>

##### steps

```ts
readonly steps: readonly {
  describes: string;
  instruction: {
     accounts?: readonly {
        address: string;
        role: AccountRole;
     }[];
     data?: string;
     programAddress: string;
  };
  semantics?: readonly PlanSemanticFact[];
  signers: readonly string[];
}[];
```

Defined in: [packages/sage/src/planning/index.ts:162](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L162)

<a id="summary-3"></a>

##### summary

```ts
readonly summary: string;
```

Defined in: [packages/sage/src/planning/index.ts:161](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L161)

<a id="v-1"></a>

##### v

```ts
readonly v: 2;
```

Defined in: [packages/sage/src/planning/index.ts:159](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L159)

***

<a id="plansequence"></a>

### PlanSequence

Defined in: [packages/sage/src/planning/plan-sequence.ts:129](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L129)

Inert, immutable itinerary with cluster-bound resume identity.

`describe()` names stable step identities only. Each actual Plan remains
lazy and must be presented separately when fresh authorization is requested.

#### Example

```ts
declare const sequence: PlanSequence;
console.log(sequence.fingerprint, sequence.describe());
```

#### Properties

<a id="cluster-1"></a>

##### cluster

```ts
readonly cluster: ClusterIdentity;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:130](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L130)

<a id="fingerprint"></a>

##### fingerprint

```ts
readonly fingerprint: PlanSequenceFingerprint;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:134](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L134)

<a id="revision-1"></a>

##### revision

```ts
readonly revision: number;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:132](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L132)

<a id="sequenceid-1"></a>

##### sequenceId

```ts
readonly sequenceId: string;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:131](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L131)

<a id="steps-5"></a>

##### steps

```ts
readonly steps: readonly PlanSequenceStep[];
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:133](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L133)

#### Methods

<a id="describe-1"></a>

##### describe()

```ts
describe(): readonly string[];
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:135](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L135)

###### Returns

readonly `string`[]

***

<a id="plansequencecheckpointv1"></a>

### PlanSequenceCheckpointV1

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:85](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L85)

Version-one caller-persisted Plan sequence checkpoint.

The value is exact-key, recursively frozen, and JSON-safe. It contains only
stable sequence identity, confirmed public evidence, current write-ahead
state, and caller-supplied local observation time.

#### Example

```ts
declare const sequence: PlanSequence;
declare const callerOwnedStore: { save(value: string): Promise<void> };
const checkpoint: PlanSequenceCheckpointV1 = createPlanSequenceCheckpoint(
  sequence,
  '2026-08-28T12:00:00.000Z',
);
await callerOwnedStore.save(stringifyPlanSequenceCheckpoint(checkpoint));
```

#### Properties

<a id="attempt"></a>

##### attempt?

```ts
readonly optional attempt?: PlanSequenceCheckpointAttemptV1;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:94](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L94)

<a id="cluster-2"></a>

##### cluster

```ts
readonly cluster: ClusterIdentity;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:88](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L88)

<a id="confirmed"></a>

##### confirmed

```ts
readonly confirmed: readonly PlanSequenceConfirmedStepV1[];
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:93](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L93)

<a id="fingerprint-1"></a>

##### fingerprint

```ts
readonly fingerprint: PlanSequenceFingerprint;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:87](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L87)

<a id="nextstepindex"></a>

##### nextStepIndex

```ts
readonly nextStepIndex: number;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:92](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L92)

<a id="observedat"></a>

##### observedAt

```ts
readonly observedAt: string;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:95](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L95)

<a id="revision-2"></a>

##### revision

```ts
readonly revision: number;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:90](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L90)

<a id="sequenceid-2"></a>

##### sequenceId

```ts
readonly sequenceId: string;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:89](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L89)

<a id="stepids"></a>

##### stepIds

```ts
readonly stepIds: readonly string[];
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:91](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L91)

<a id="v-2"></a>

##### v

```ts
readonly v: 1;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:86](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L86)

***

<a id="plansequenceconfirmedstepv1"></a>

### PlanSequenceConfirmedStepV1

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:28](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L28)

Persisted public confirmation evidence for one completed sequence step.

Slots use canonical unsigned decimal strings so checkpoint values remain
directly JSON-serializable without losing integer precision.

#### Example

```ts
declare const confirmed: PlanSequenceConfirmedStepV1;
console.log(confirmed.stepId, confirmed.slot);
```

#### Properties

<a id="commitment-4"></a>

##### commitment

```ts
readonly commitment: "confirmed" | "finalized";
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:33](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L33)

<a id="index"></a>

##### index

```ts
readonly index: number;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:30](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L30)

<a id="signature-1"></a>

##### signature

```ts
readonly signature: Signature;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:31](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L31)

<a id="slot-1"></a>

##### slot

```ts
readonly slot: string;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:32](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L32)

<a id="stepid"></a>

##### stepId

```ts
readonly stepId: string;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:29](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L29)

***

<a id="plansequencepresentation"></a>

### PlanSequencePresentation

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:55](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L55)

Fresh single-transaction authorization detail presented before signing.

#### Example

```ts
declare const presentation: PlanSequencePresentation;
console.log(presentation.stepId, presentation.description);
```

#### Properties

<a id="description"></a>

##### description

```ts
readonly description: readonly string[];
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:59](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L59)

<a id="index-1"></a>

##### index

```ts
readonly index: number;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:57](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L57)

<a id="plan-1"></a>

##### plan

```ts
readonly plan: Plan;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:58](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L58)

<a id="stepid-1"></a>

##### stepId

```ts
readonly stepId: string;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:56](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L56)

***

<a id="plansequencestep"></a>

### PlanSequenceStep

Defined in: [packages/sage/src/planning/plan-sequence.ts:93](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L93)

One stable lazy step in a Plan sequence.

The callback may close over capability context. It creates no Plan until the
caller reaches this step and invokes it with current progress.

#### Example

```ts
declare const plan: Plan;
const step: PlanSequenceStep = {
  id: 'undock',
  prepare: async () => ({ status: 'ready', plan }),
};
```

#### Properties

<a id="id"></a>

##### id

```ts
readonly id: string;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:94](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L94)

#### Methods

<a id="prepare"></a>

##### prepare()

```ts
prepare(context): Promise<PlanSequenceReadiness>;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:95](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L95)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`PlanSequenceStepContext`](/reference/planning/#plansequencestepcontext) |

###### Returns

`Promise`\<[`PlanSequenceReadiness`](/reference/planning/#plansequencereadiness)\>

***

<a id="plansequencestore"></a>

### PlanSequenceStore

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:43](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L43)

Caller-owned durable checkpoint boundary.

Resolution of `save()` acknowledges that the checkpoint is durable. The SDK
never signs or enters a submission boundary until the required save resolves.

#### Example

```ts
const store: PlanSequenceStore = {
  save: async (checkpoint) => localStorage.setItem('journey', JSON.stringify(checkpoint)),
};
```

#### Methods

<a id="save"></a>

##### save()

```ts
save(checkpoint): Promise<void>;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:44](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L44)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `checkpoint` | [`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1) |

###### Returns

`Promise`\<`void`\>

***

<a id="planstep"></a>

### PlanStep

Defined in: [packages/sage/src/planning/index.ts:76](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L76)

One ordered instruction and its game-language signer requirements.

#### Example

```ts
declare const step: PlanStep;
console.log(step.describes, step.signers);
```

#### Properties

<a id="describes"></a>

##### describes

```ts
readonly describes: string;
```

Defined in: [packages/sage/src/planning/index.ts:78](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L78)

<a id="instruction"></a>

##### instruction

```ts
readonly instruction: Instruction<string, readonly AccountMeta<string>[]>;
```

Defined in: [packages/sage/src/planning/index.ts:77](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L77)

<a id="semantics"></a>

##### semantics?

```ts
readonly optional semantics?: readonly PlanSemanticFact[];
```

Defined in: [packages/sage/src/planning/index.ts:79](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L79)

<a id="signers-2"></a>

##### signers

```ts
readonly signers: readonly Address[];
```

Defined in: [packages/sage/src/planning/index.ts:80](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L80)

***

<a id="simulationresult"></a>

### SimulationResult

Defined in: [packages/sage/src/planning/simulation.ts:40](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L40)

Node-provenance result from simulating one unsigned Plan.

#### Example

```ts
declare const result: SimulationResult;
console.log(result.slot, result.replacementBlockhash.blockhash);
```

#### Properties

<a id="logs"></a>

##### logs

```ts
readonly logs: readonly string[];
```

Defined in: [packages/sage/src/planning/simulation.ts:43](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L43)

<a id="replacementblockhash"></a>

##### replacementBlockhash

```ts
readonly replacementBlockhash: Readonly<{
  blockhash: string;
  lastValidBlockHeight: bigint;
}>;
```

Defined in: [packages/sage/src/planning/simulation.ts:45](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L45)

<a id="returndata"></a>

##### returnData?

```ts
readonly optional returnData?: SimulationReturnData;
```

Defined in: [packages/sage/src/planning/simulation.ts:44](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L44)

<a id="slot-2"></a>

##### slot

```ts
readonly slot: bigint;
```

Defined in: [packages/sage/src/planning/simulation.ts:41](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L41)

<a id="unitsconsumed"></a>

##### unitsConsumed

```ts
readonly unitsConsumed: bigint | undefined;
```

Defined in: [packages/sage/src/planning/simulation.ts:42](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L42)

***

<a id="simulationreturndata"></a>

### SimulationReturnData

Defined in: [packages/sage/src/planning/simulation.ts:27](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L27)

Return data emitted by the last program to set it during simulation.

#### Example

```ts
declare const returnData: SimulationReturnData;
console.log(returnData.programAddress, returnData.data);
```

#### Properties

<a id="data"></a>

##### data

```ts
readonly data: string;
```

Defined in: [packages/sage/src/planning/simulation.ts:29](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L29)

<a id="programaddress"></a>

##### programAddress

```ts
readonly programAddress: Address;
```

Defined in: [packages/sage/src/planning/simulation.ts:28](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L28)

## Type Aliases

<a id="confirmedstep"></a>

### ConfirmedStep

```ts
type ConfirmedStep = Readonly<{
  commitment: "confirmed" | "finalized";
  index: number;
  signature: Signature;
  slot: bigint;
  stepId: string;
}>;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:37](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L37)

Public confirmation evidence available to later lazy step preparation.

#### Example

```ts
declare const confirmed: ConfirmedStep;
console.log(confirmed.stepId, confirmed.signature);
```

***

<a id="planexecutionresult"></a>

### PlanExecutionResult

```ts
type PlanExecutionResult = 
  | ConfirmedPlanExecution
  | UnknownPlanExecution;
```

Defined in: [packages/sage/src/planning/execution.ts:114](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L114)

Every non-throwing terminal outcome from `executePlan`.

#### Example

```ts
declare const result: PlanExecutionResult;
if (result.status === 'unknown') console.log(result.signature);
```

***

<a id="planprecondition"></a>

### PlanPrecondition

```ts
type PlanPrecondition = 
  | {
  address: Address;
  dataHash: string;
  describes: string;
  kind: "account-state";
}
  | {
  address: Address;
  dataHash?: never;
  describes: string;
  kind: "account-absent";
};
```

Defined in: [packages/sage/src/planning/index.ts:91](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L91)

A closure-free whole-account freshness guard recorded at planning time.

#### Example

```ts
declare const precondition: PlanPrecondition;
console.log(precondition.address, precondition.kind);
```

***

<a id="plansemanticfact"></a>

### PlanSemanticFact

```ts
type PlanSemanticFact = 
  | {
  kind: "exclusive";
  scope: "transaction";
}
  | {
  fact: string;
  kind: "requires";
  resource: string;
}
  | {
  fact: string;
  kind: "invalidates";
  resource: string;
}
  | {
  from: string;
  kind: "transition";
  resource: string;
  to: string;
};
```

Defined in: [packages/sage/src/planning/index.ts:45](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L45)

One capability-authored opaque fact used to review Plan composition.

The planning core preserves these exact strings without interpreting
capability vocabulary or inferring negation conventions.

#### Union Members

##### Type Literal

```ts
{
  kind: "exclusive";
  scope: "transaction";
}
```

###### kind

```ts
readonly kind: "exclusive";
```

Requires this step to be the only instruction in its transaction.

###### scope

```ts
readonly scope: "transaction";
```

***

##### Type Literal

```ts
{
  fact: string;
  kind: "requires";
  resource: string;
}
```

***

##### Type Literal

```ts
{
  fact: string;
  kind: "invalidates";
  resource: string;
}
```

***

##### Type Literal

```ts
{
  from: string;
  kind: "transition";
  resource: string;
  to: string;
}
```

#### Example

```ts
const fact: PlanSemanticFact = {
  kind: 'requires',
  resource: 'fleet:Ravager',
  fact: 'idle',
};
```

***

<a id="plansequencecheckpointattemptv1"></a>

### PlanSequenceCheckpointAttemptV1

```ts
type PlanSequenceCheckpointAttemptV1 = 
  | Readonly<{
  index: number;
  phase: "prepared";
  signerMode: "observable" | "opaque";
  stepId: string;
}>
  | Readonly<{
  index: number;
  phase: "signed";
  signature: Signature;
  signerMode: "observable";
  stepId: string;
}>
  | Readonly<{
  index: number;
  phase: "invoking";
  signerMode: "opaque";
  stepId: string;
}>;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:47](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L47)

One durable write-ahead attempt at the checkpoint's next step.

Observable signers persist `signed` with their public signature. Opaque
combined sign/send signers persist `invoking` before entering that boundary.

#### Example

```ts
declare const attempt: PlanSequenceCheckpointAttemptV1;
console.log(attempt.stepId, attempt.phase);
```

***

<a id="plansequenceerrorcode"></a>

### PlanSequenceErrorCode

```ts
type PlanSequenceErrorCode = 
  | "SEQUENCE_IDENTITY_MISMATCH"
  | "SEQUENCE_CHECKPOINT_INVALID"
  | "SEQUENCE_CONFIRMATION_UNVERIFIABLE"
  | "SEQUENCE_ATTEMPT_UNRESOLVED"
  | "SEQUENCE_PREPARATION_FAILED"
  | "SEQUENCE_PERSISTENCE_FAILED"
  | "SEQUENCE_PRESENTATION_FAILED";
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:181](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L181)

Sequence-owned failure codes that never carry raw callback diagnostics.

#### Example

```ts
const code: PlanSequenceErrorCode = 'SEQUENCE_PREPARATION_FAILED';
```

***

<a id="plansequencefingerprint-1"></a>

### PlanSequenceFingerprint

```ts
type PlanSequenceFingerprint = string & {
  [PLAN_SEQUENCE_FINGERPRINT_BRAND]: true;
};
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:25](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L25)

Stable SHA-256 identity for one cluster-bound ordered Plan sequence.

#### Type Declaration

##### \[PLAN\_SEQUENCE\_FINGERPRINT\_BRAND\]

```ts
readonly [PLAN_SEQUENCE_FINGERPRINT_BRAND]: true;
```

#### Example

```ts
declare const fingerprint: PlanSequenceFingerprint;
console.log(fingerprint.length); // 64
```

***

<a id="plansequencephase"></a>

### PlanSequencePhase

```ts
type PlanSequencePhase = 
  | "preparing"
  | "prepared"
  | "signing"
  | "signed"
  | "invoking"
  | "submitted"
  | "confirmed";
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:165](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L165)

Finite lifecycle phase safe to expose in a sequence result.

#### Example

```ts
const phase: PlanSequencePhase = 'preparing';
```

***

<a id="plansequencereadiness"></a>

### PlanSequenceReadiness

```ts
type PlanSequenceReadiness = 
  | Readonly<{
  plan: Plan;
  status: "ready";
}>
  | Readonly<{
  notBefore?: string;
  reason: string;
  status: "waiting";
}>;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:71](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L71)

Exact result of freshly preparing one sequence step.

A waiting timestamp is a canonical UTC ISO-8601 string. It is advisory; the
planning core neither interprets it nor polls automatically.

#### Example

```ts
declare const readiness: PlanSequenceReadiness;
if (readiness.status === 'ready') console.log(readiness.plan.describe());
```

***

<a id="plansequenceresult"></a>

### PlanSequenceResult

```ts
type PlanSequenceResult<Checkpoint> = 
  | Readonly<{
  checkpoint: Checkpoint;
  index: number;
  notBefore?: string;
  phase: "preparing";
  reason: string;
  status: "waiting";
  stepId: string;
}>
  | Readonly<{
  checkpoint: Checkpoint;
  index: number;
  phase: "preparing" | "confirmed";
  status: "paused";
  stepId: string;
}>
  | Readonly<{
  checkpoint: Checkpoint;
  code: PlanSequenceResultCode;
  index: number;
  message: string;
  phase: "preparing" | "prepared" | "signing";
  status: "failed";
  stepId: string;
}>
  | Readonly<{
  checkpoint: Checkpoint;
  code: "SEQUENCE_PERSISTENCE_FAILED";
  index: number;
  message: string;
  phase: "signed";
  signature: Signature;
  status: "failed";
  stepId: string;
}>
  | Readonly<{
  checkpoint: Checkpoint;
  code: PlanSequenceResultCode;
  index: number;
  message: string;
  phase: "signed" | "invoking" | "submitted";
  signature?: Signature;
  status: "unknown";
  stepId: string;
}>
  | Readonly<{
  checkpoint: Checkpoint;
  index: number;
  phase: "confirmed";
  signature?: Signature;
  status: "completed";
  stepId: string;
}>;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:216](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L216)

Finite safe result envelope for future checkpoint-backed coordination.

The checkpoint codec supplies the generic checkpoint value. Raw errors,
signers, transactions, blockhashes, and callback values are never fields.
A boundary pause is `preparing` before the first step or `confirmed` after a
completed step. If saving an observable signed attempt fails before
submission, the result remains a signature-bearing `failed` outcome.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `Checkpoint` | `unknown` |

#### Example

```ts
declare const result: PlanSequenceResult<{ readonly v: 1 }>;
if (result.status === 'failed') console.log(result.code, result.message);
```

***

<a id="plansequenceresultcode"></a>

### PlanSequenceResultCode

```ts
type PlanSequenceResultCode = 
  | PlanSequenceErrorCode
  | SageSdkErrorCode;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:200](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L200)

Finite error code carried by a failed or unknown sequence result.

Existing planning and execution errors retain their public SDK code; errors
crossing callback or persistence boundaries use a sequence-owned code.

#### Example

```ts
const code: PlanSequenceResultCode = 'INVALID_ACTION_INPUT';
```

***

<a id="plansequencestatus"></a>

### PlanSequenceStatus

```ts
type PlanSequenceStatus = "waiting" | "paused" | "failed" | "unknown" | "completed";
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:155](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L155)

Every public sequence coordination status.

`completed` is the only successful terminal status.

#### Example

```ts
const status: PlanSequenceStatus = 'waiting';
```

***

<a id="plansequencestepcontext"></a>

### PlanSequenceStepContext

```ts
type PlanSequenceStepContext = Readonly<{
  confirmed: readonly ConfirmedStep[];
  index: number;
  sequenceId: string;
  stepId: string;
}>;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:53](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L53)

Stable sequence progress supplied to one capability-owned step callback.

#### Example

```ts
declare const context: PlanSequenceStepContext;
console.log(context.sequenceId, context.stepId, context.confirmed.length);
```

***

<a id="unknownplanexecution"></a>

### UnknownPlanExecution

```ts
type UnknownPlanExecution = 
  | Readonly<{
  lastCheckedBlockHeight: bigint;
  lastValidBlockHeight: bigint | null;
  reason: "timeout";
  signature: Signature;
  status: "unknown";
}>
  | Readonly<{
  lastCheckedBlockHeight: bigint | null;
  lastValidBlockHeight: bigint | null;
  operation: "submission" | "signature-status" | "block-height";
  reason: "transport-error";
  signature: Signature;
  status: "unknown";
}>;
```

Defined in: [packages/sage/src/planning/execution.ts:89](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L89)

A submitted transaction whose terminal state remains unknown.

#### Example

```ts
declare const result: UnknownPlanExecution;
console.log(result.signature, result.lastValidBlockHeight);
```

## Functions

<a id="assembleplan"></a>

### assemblePlan()

```ts
function assemblePlan(
   context, 
   plan, 
   policy): Promise<Readonly<{
  messageBytes: TransactionMessageBytes;
  signatures: SignaturesMap;
}> & TransactionWithBlockhashLifetime>;
```

Defined in: [packages/sage/src/planning/assembly.ts:276](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L276)

Assembles one Plan into an unsigned blockhash-lifetime transaction.

Assembly validates compute and priority-fee policy before RPC, fetches one
latest blockhash, and never signs, simulates, or submits the transaction.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `plan` | [`Plan`](/reference/planning/#plan) |
| `policy` | [`AssemblyPolicy`](/reference/planning/#assemblypolicy) |

#### Returns

`Promise`\<`Readonly`\<\{
  `messageBytes`: `TransactionMessageBytes`;
  `signatures`: `SignaturesMap`;
\}\> & `TransactionWithBlockhashLifetime`\>

#### Example

```ts
declare const ctx: SageContext;
declare const plan: Plan;
declare const feePayer: Address;
const transaction = await assemblePlan(ctx, plan, { feePayer });
```

***

<a id="combineplans"></a>

### combinePlans()

```ts
function combinePlans(...plans): Plan;
```

Defined in: [packages/sage/src/planning/index.ts:819](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L819)

Combines one or more Plans with deterministic associative flattening.

Semantic validation is eager. Conflict indices are relative to the flattened
inputs of the `combinePlans` call that rejects them.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`plans` | readonly [`Plan`](/reference/planning/#plan)[] |

#### Returns

[`Plan`](/reference/planning/#plan)

#### Example

```ts
declare const undock: Plan;
declare const warp: Plan;
const movement = combinePlans(undock, warp);
console.log(movement.summary);
```

***

<a id="confirmplansequencecheckpointstep"></a>

### confirmPlanSequenceCheckpointStep()

```ts
function confirmPlanSequenceCheckpointStep(
   checkpoint, 
   evidence, 
   observedAt): PlanSequenceCheckpointV1;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:717](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L717)

Appends public confirmation evidence and advances exactly one sequence step.

A step can advance only from its matching durable `signed` or `invoking`
attempt. The attempt is cleared in the returned checkpoint.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `checkpoint` | [`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1) |
| `evidence` | [`ConfirmedStep`](/reference/planning/#confirmedstep) |
| `observedAt` | `string` |

#### Returns

[`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1)

#### Example

```ts
declare const checkpoint: PlanSequenceCheckpointV1;
declare const confirmed: ConfirmedStep;
const advanced = confirmPlanSequenceCheckpointStep(
  checkpoint,
  confirmed,
  '2026-08-28T12:00:00.000Z',
);
```

***

<a id="createplan"></a>

### createPlan()

```ts
function createPlan(input): Plan;
```

Defined in: [packages/sage/src/planning/index.ts:614](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L614)

Creates an inert branded Plan while deriving every aggregate field.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`CreatePlanInput`](/reference/planning/#createplaninput) |

#### Returns

[`Plan`](/reference/planning/#plan)

#### Example

```ts
declare const step: PlanStep;
const plan = createPlan({
  kind: 'fleet.move',
  summary: 'Move the fleet.',
  steps: [step],
  preconditions: [],
});
console.log(plan.affected);
```

***

<a id="createplansequence"></a>

### createPlanSequence()

```ts
function createPlanSequence(input): Promise<PlanSequence>;
```

Defined in: [packages/sage/src/planning/plan-sequence.ts:588](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L588)

Creates an inert Plan sequence and its canonical cluster-bound fingerprint.

Construction invokes no step callback and performs no context, wallet,
signer, or network work. The only asynchronous operation is WebCrypto
SHA-256 over the accepted canonical identity bytes.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`CreatePlanSequenceInput`](/reference/planning/#createplansequenceinput) |

#### Returns

`Promise`\<[`PlanSequence`](/reference/planning/#plansequence)\>

#### Example

```ts
declare const undockPlan: Plan;
declare const dockPlan: Plan;
const sequence = await createPlanSequence({
  cluster: 'zink-ptr',
  sequenceId: 'fleet-round-trip',
  revision: 0,
  steps: [
    {
      id: 'undock',
      prepare: async () => ({ status: 'ready', plan: undockPlan }),
    },
    {
      id: 'dock',
      prepare: async ({ confirmed }) =>
        confirmed.length === 0
          ? {
              status: 'waiting',
              reason: 'Wait for undock confirmation.',
              notBefore: '2026-08-28T12:05:00.000Z',
            }
          : { status: 'ready', plan: dockPlan },
    },
  ],
});
console.table(sequence.describe());
```

***

<a id="createplansequencecheckpoint"></a>

### createPlanSequenceCheckpoint()

```ts
function createPlanSequenceCheckpoint(sequence, observedAt): PlanSequenceCheckpointV1;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:508](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L508)

Creates an empty checkpoint bound to one exact Plan sequence.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `sequence` | [`PlanSequence`](/reference/planning/#plansequence) |
| `observedAt` | `string` |

#### Returns

[`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1)

#### Example

```ts
declare const sequence: PlanSequence;
const checkpoint = createPlanSequenceCheckpoint(
  sequence,
  '2026-08-28T12:00:00.000Z',
);
console.log(checkpoint.nextStepIndex); // 0
```

***

<a id="executeplan"></a>

### executePlan()

```ts
function executePlan(
   context, 
   plan, 
options): Promise<PlanExecutionResult>;
```

Defined in: [packages/sage/src/planning/execution.ts:894](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L894)

Executes one Plan through local signer matching, freshness re-check, one
submission, terminal confirmation, and confirmed-only cache invalidation.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `plan` | [`Plan`](/reference/planning/#plan) |
| `options` | [`ExecutePlanOptions`](/reference/planning/#executeplanoptions) |

#### Returns

`Promise`\<[`PlanExecutionResult`](/reference/planning/#planexecutionresult)\>

#### Example

```ts
import type { TransactionSigner } from '@solana/kit';

declare const ctx: SageContext;
declare const plan: Plan;
declare const feePayer: TransactionSigner;
const result = await executePlan(ctx, plan, { feePayer });
console.log(result.status, result.signature);
```

***

<a id="executeplansequence"></a>

### executePlanSequence()

```ts
function executePlanSequence(
   context, 
   sequence, 
   checkpointSource, 
options): Promise<SequenceResult>;
```

Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:367](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L367)

Executes or resumes one PlanSequence invocation without polling or retrying.

The checkpoint may be an SDK-created object, caller-owned decoded JSON, or a
JSON string. It is strictly parsed against the exact sequence before any RPC,
preparation, presentation, or signer work begins.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `sequence` | [`PlanSequence`](/reference/planning/#plansequence) |
| `checkpointSource` | `unknown` |
| `options` | [`ExecutePlanSequenceOptions`](/reference/planning/#executeplansequenceoptions) |

#### Returns

`Promise`\<`SequenceResult`\>

#### Example

```ts
declare const ctx: SageContext;
declare const sequence: PlanSequence;
declare const feePayer: ExecutePlanSequenceOptions['feePayer'];
let checkpointJson = stringifyPlanSequenceCheckpoint(
  createPlanSequenceCheckpoint(sequence, '2026-08-28T12:00:00.000Z'),
);
const store: PlanSequenceStore = {
  save: async (checkpoint) => {
    checkpointJson = stringifyPlanSequenceCheckpoint(checkpoint);
  },
};
const controller = new AbortController();
controller.abort();
const paused = await executePlanSequence(ctx, sequence, checkpointJson, {
  feePayer,
  signal: controller.signal,
  store,
});
checkpointJson = stringifyPlanSequenceCheckpoint(paused.checkpoint);
const result = await executePlanSequence(ctx, sequence, checkpointJson, {
  feePayer,
  store,
  onBeforeSign: async ({ plan, description }) => {
    console.log(plan.summary);
    console.table(description);
  },
});
if (result.status === 'completed') console.log(result.signature);
```

***

<a id="parseplansequencecheckpoint"></a>

### parsePlanSequenceCheckpoint()

```ts
function parsePlanSequenceCheckpoint(sequence, source): PlanSequenceCheckpointV1;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:537](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L537)

Parses and validates a checkpoint against one exact Plan sequence.

The source may be a JSON string or a caller-owned parsed JSON value.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `sequence` | [`PlanSequence`](/reference/planning/#plansequence) |
| `source` | `unknown` |

#### Returns

[`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1)

#### Example

```ts
declare const sequence: PlanSequence;
declare const storedJson: string;
const checkpoint = parsePlanSequenceCheckpoint(sequence, storedJson);
console.log(checkpoint.nextStepIndex);
```

***

<a id="planfromjson"></a>

### planFromJSON()

```ts
function planFromJSON(json): Plan;
```

Defined in: [packages/sage/src/planning/index.ts:698](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L698)

Rehydrates and validates a complete versioned Plan wire value.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `json` | `unknown` |

#### Returns

[`Plan`](/reference/planning/#plan)

#### Example

```ts
declare const wire: PlanJsonV1 | PlanJsonV2;
const plan = planFromJSON(wire);
console.log(plan.describe());
```

***

<a id="setplansequencecheckpointattempt"></a>

### setPlanSequenceCheckpointAttempt()

```ts
function setPlanSequenceCheckpointAttempt(
   checkpoint, 
   attempt, 
   observedAt): PlanSequenceCheckpointV1;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:649](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L649)

Replaces the current write-ahead attempt without advancing sequence progress.

The first attempt must be `prepared`. An observable attempt may then become
`signed`; an opaque attempt may become `invoking`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `checkpoint` | [`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1) |
| `attempt` | [`PlanSequenceCheckpointAttemptV1`](/reference/planning/#plansequencecheckpointattemptv1) |
| `observedAt` | `string` |

#### Returns

[`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1)

#### Example

```ts
declare const checkpoint: PlanSequenceCheckpointV1;
const prepared = setPlanSequenceCheckpointAttempt(
  checkpoint,
  {
    stepId: checkpoint.stepIds[checkpoint.nextStepIndex]!,
    index: checkpoint.nextStepIndex,
    phase: 'prepared',
    signerMode: 'observable',
  },
  '2026-08-28T12:00:00.000Z',
);
```

***

<a id="simulateplan"></a>

### simulatePlan()

```ts
function simulatePlan(
   context, 
   plan, 
policy): Promise<SimulationResult>;
```

Defined in: [packages/sage/src/planning/simulation.ts:85](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L85)

Simulates one Plan without receiving or invoking a signer.

The same assembly policy used for execution produces the unsigned transaction.
The node replaces its recent blockhash and verifies no signatures.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `plan` | [`Plan`](/reference/planning/#plan) |
| `policy` | [`AssemblyPolicy`](/reference/planning/#assemblypolicy) |

#### Returns

`Promise`\<[`SimulationResult`](/reference/planning/#simulationresult)\>

#### Example

```ts
declare const ctx: SageContext;
declare const plan: Plan;
declare const feePayer: Address;
const result = await simulatePlan(ctx, plan, { feePayer });
console.log(result.logs, result.unitsConsumed);
```

***

<a id="stringifyplansequencecheckpoint"></a>

### stringifyPlanSequenceCheckpoint()

```ts
function stringifyPlanSequenceCheckpoint(checkpoint): string;
```

Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:801](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L801)

Serializes one SDK-created checkpoint to canonical compact JSON.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `checkpoint` | [`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1) |

#### Returns

`string`

#### Example

```ts
declare const checkpoint: PlanSequenceCheckpointV1;
declare const callerOwnedStore: { save(value: string): Promise<void> };
const storedJson = stringifyPlanSequenceCheckpoint(checkpoint);
await callerOwnedStore.save(storedJson);
```