# 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
### 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
##### 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)
##### 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)
##### 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)
##### 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)
***
### ConfirmedPlanExecution
Defined in: [packages/sage/src/planning/execution.ts:169](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L169)
A transaction confirmed at the requested commitment.
#### Example
```ts
declare const result: ConfirmedPlanExecution;
console.log(result.signature, result.slot);
```
#### Properties
##### commitment
```ts
readonly commitment: Commitment;
```
Defined in: [packages/sage/src/planning/execution.ts:173](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L173)
##### signature
```ts
readonly signature: Signature;
```
Defined in: [packages/sage/src/planning/execution.ts:171](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L171)
##### slot
```ts
readonly slot: bigint;
```
Defined in: [packages/sage/src/planning/execution.ts:172](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L172)
##### status
```ts
readonly status: "confirmed";
```
Defined in: [packages/sage/src/planning/execution.ts:170](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L170)
***
### CreatePlanInput
Defined in: [packages/sage/src/planning/index.ts:504](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L504)
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
##### kind
```ts
readonly kind: string;
```
Defined in: [packages/sage/src/planning/index.ts:505](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L505)
##### preconditions
```ts
readonly preconditions: readonly PlanPrecondition[];
```
Defined in: [packages/sage/src/planning/index.ts:508](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L508)
##### steps
```ts
readonly steps: readonly PlanStep[];
```
Defined in: [packages/sage/src/planning/index.ts:507](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L507)
##### summary
```ts
readonly summary: string;
```
Defined in: [packages/sage/src/planning/index.ts:506](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L506)
***
### 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
##### 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)
##### 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)
##### 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)
##### 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)
***
### ExecutePlanOptions
Defined in: [packages/sage/src/planning/execution.ts:151](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L151)
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
##### commitment?
```ts
readonly optional commitment?: Commitment;
```
Defined in: [packages/sage/src/planning/execution.ts:156](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L156)
##### computeUnitLimit?
```ts
readonly optional computeUnitLimit?: number;
```
Defined in: [packages/sage/src/planning/execution.ts:154](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L154)
##### feePayer
```ts
readonly feePayer: TransactionSigner;
```
Defined in: [packages/sage/src/planning/execution.ts:152](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L152)
##### pollIntervalMs?
```ts
readonly optional pollIntervalMs?: number;
```
Defined in: [packages/sage/src/planning/execution.ts:158](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L158)
##### priorityFeeMicroLamports?
```ts
readonly optional priorityFeeMicroLamports?: bigint;
```
Defined in: [packages/sage/src/planning/execution.ts:155](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L155)
##### signers?
```ts
readonly optional signers?: readonly TransactionSigner[];
```
Defined in: [packages/sage/src/planning/execution.ts:153](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L153)
##### timeoutMs?
```ts
readonly optional timeoutMs?: number;
```
Defined in: [packages/sage/src/planning/execution.ts:157](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L157)
***
### ExecutePlanSequenceOptions
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:82](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L82)
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
##### commitment?
```ts
readonly optional commitment?: "confirmed" | "finalized";
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:86](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L86)
##### computeUnitLimit?
```ts
readonly optional computeUnitLimit?: number;
```
Defined in: [packages/sage/src/planning/execution.ts:154](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L154)
###### Inherited from
[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`computeUnitLimit`](/reference/planning/#executeplanoptions)
##### feePayer
```ts
readonly feePayer: TransactionSigner;
```
Defined in: [packages/sage/src/planning/execution.ts:152](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L152)
###### Inherited from
[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`feePayer`](/reference/planning/#executeplanoptions)
##### onBeforeSign?
```ts
readonly optional onBeforeSign?: (presentation) => Promise;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:89](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L89)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `presentation` | [`PlanSequencePresentation`](/reference/planning/#plansequencepresentation) |
###### Returns
`Promise`\<`void`\>
##### pollIntervalMs?
```ts
readonly optional pollIntervalMs?: number;
```
Defined in: [packages/sage/src/planning/execution.ts:158](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L158)
###### Inherited from
[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`pollIntervalMs`](/reference/planning/#executeplanoptions)
##### priorityFeeMicroLamports?
```ts
readonly optional priorityFeeMicroLamports?: bigint;
```
Defined in: [packages/sage/src/planning/execution.ts:155](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L155)
###### Inherited from
[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`priorityFeeMicroLamports`](/reference/planning/#executeplanoptions)
##### signal?
```ts
readonly optional signal?: AbortSignal;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:88](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L88)
##### signers?
```ts
readonly optional signers?: readonly TransactionSigner[];
```
Defined in: [packages/sage/src/planning/execution.ts:153](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L153)
###### Inherited from
[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`signers`](/reference/planning/#executeplanoptions)
##### store
```ts
readonly store: PlanSequenceStore;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:87](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L87)
##### timeoutMs?
```ts
readonly optional timeoutMs?: number;
```
Defined in: [packages/sage/src/planning/execution.ts:157](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L157)
###### Inherited from
[`ExecutePlanOptions`](/reference/planning/#executeplanoptions).[`timeoutMs`](/reference/planning/#executeplanoptions)
***
### Plan
Defined in: [packages/sage/src/planning/index.ts:476](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L476)
Inert, inspectable action data built only through planning factories.
#### Example
```ts
declare const plan: Plan;
console.log(plan.summary);
console.log(plan.describe());
```
#### Properties
##### \[PLAN\_BRAND\]
```ts
readonly [PLAN_BRAND]: true;
```
Defined in: [packages/sage/src/planning/index.ts:485](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L485)
##### affected
```ts
readonly affected: readonly Address[];
```
Defined in: [packages/sage/src/planning/index.ts:481](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L481)
##### kind
```ts
readonly kind: string;
```
Defined in: [packages/sage/src/planning/index.ts:477](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L477)
##### preconditions
```ts
readonly preconditions: readonly PlanPrecondition[];
```
Defined in: [packages/sage/src/planning/index.ts:480](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L480)
##### requiredSigners
```ts
readonly requiredSigners: readonly Address[];
```
Defined in: [packages/sage/src/planning/index.ts:482](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L482)
##### steps
```ts
readonly steps: readonly PlanStep[];
```
Defined in: [packages/sage/src/planning/index.ts:479](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L479)
##### summary
```ts
readonly summary: string;
```
Defined in: [packages/sage/src/planning/index.ts:478](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L478)
#### Methods
##### describe()
```ts
describe(): readonly string[];
```
Defined in: [packages/sage/src/planning/index.ts:483](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L483)
###### Returns
readonly `string`[]
##### toJSON()
```ts
toJSON(): PlanJson;
```
Defined in: [packages/sage/src/planning/index.ts:484](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L484)
###### Returns
[`PlanJson`](/reference/planning/#planjson)
***
### PlanJson
Defined in: [packages/sage/src/planning/index.ts:439](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L439)
The current persistent Plan format. Unsupported versions require a fresh Plan.
#### Example
```ts
declare const plan: Plan;
const wire: PlanJson = plan.toJSON();
console.log(wire.v);
const restored = planFromJSON(wire);
```
#### Properties
##### affected
```ts
readonly affected: readonly string[];
```
Defined in: [packages/sage/src/planning/index.ts:463](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L463)
##### kind
```ts
readonly kind: string;
```
Defined in: [packages/sage/src/planning/index.ts:441](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L441)
##### preconditions
```ts
readonly preconditions: readonly (
| RuntimeGuardJson
| {
address: string;
character: string;
dataHash?: undefined;
describes: string;
intent: {
authorization: {
authority: string;
keyIndex: number;
profile: string;
};
fleet: string;
game: string;
journey: {
departure: string;
duration: string;
from: {
x: string;
y: string;
};
kind: "subwarp";
to: {
x: string;
y: string;
};
};
profile: string;
};
kind: "fleet-arrival";
regionTracker: string;
}
| {
address: string;
authority: string;
certificate: string;
character: string;
dataHash?: undefined;
describes: string;
game: string;
keyIndex: number;
kind: "fleet-dock-funding";
profile: string;
reason: | "unsupported-account-layout"
| "unsupported-fleet-state"
| "noncanonical-account-encoding"
| "stale-definition-sequences"
| "stale-starbase-sequence"
| "pending-recovery"
| "active-stimulants"
| "funding-state-unavailable"
| "accounts-below-rent-reserve"
| "profile-below-storage-ceiling";
starbasePlayer: string;
status: "unavailable";
system: string;
}
| {
address: string;
authority: string;
cargoSequenceId: number;
certificate: string;
character: string;
dataHash?: undefined;
describes: string;
fleetDataLengthBytes: number;
game: string;
keyIndex: number;
kind: "fleet-dock-funding";
maximumProfileDebit: string;
profile: string;
rentExemptionThreshold: number;
rentLamportsPerByteYear: string;
shipSequenceId: number;
starbasePlayer: string;
starbaseSequenceId: string;
status: "available";
system: string;
}
| {
address: string;
authority: string;
count: number;
dataHash?: undefined;
describes: string;
direction: "load" | "unload";
game: string;
keyIndex: number;
kind: "fleet-crew-transfer";
profile: string;
starbasePlayer: string;
system: string;
systemSequenceId: string;
}
| {
address: string;
authority: string;
character: string;
configHash: string;
dataHash?: undefined;
describes: string;
expectedSequence: string;
focus: number;
game: string;
keyIndex: number;
kind: "scan-detect";
loot: string;
pattern: string;
patternId: number;
policy: string;
policyRevision: number;
profile: string;
profileRevision: number;
signal: string;
tracker: string;
}
| {
address: string;
authority: string;
character: string;
configHash: string;
dataHash?: undefined;
describes: string;
expectedSequence: string;
game: string;
keyIndex: number;
kind: "scan-completion";
loot: string;
operation: | "resolve"
| "recover"
| "acknowledge"
| "abandon"
| "expire"
| "forfeit-entropy";
policy: string;
profile: string;
signal: string;
status: number;
xpBudget: string;
xpConfig: string;
}
| {
address: string;
dataHash?: undefined;
defender: string;
defenderProfile: string;
describes: string;
game: string;
instructionKey: string;
kind: "fleet-attack";
profile: string;
}
| {
address: string;
authority: string;
dataHash?: undefined;
describes: string;
fleetHash: string;
game: string;
keyIndex: number;
kind: "fleet-respawn";
maximumProfileDebit: string;
maximumRecoveryFee: string;
phase: "complete" | "start";
profile: string;
system: string;
}
| {
address: string;
dataHash?: undefined;
describes: string;
game: string;
kind: "currency-cache";
}
| {
address: string;
dataHash?: undefined;
describes: string;
game: string;
kind: "movement-character";
profile: string;
stateHash: string;
}
| {
address: string;
dataHash?: undefined;
describes: string;
game: string;
kind: "fleet-docking-policy";
ownership: string;
starbasePlayer: string;
system: string;
}
| {
address: string;
dataHash?: undefined;
describes: string;
game: string;
kind: "starbase-system";
requireCss?: true;
starbaseSequenceId: string;
}
| {
address: string;
budgetLamports: string;
characterLamports: string;
characterSize: number;
dataHash?: undefined;
describes: string;
funder: string;
game: string;
initializationHash: string;
kind: "character-registration";
maximumFunderDebit: string;
profile: string;
profileDataHash: string;
xpBudget: string;
xpBudgetConfig: string;
}
| {
address: string;
dataHash?: undefined;
describes: string;
game: string;
kind: "ship-import-funding";
maximumProfileDebit: string;
profile: string;
shipId: number;
system: string;
}
| {
address: string;
asteroid: string;
dataHash?: undefined;
describes: string;
game: string;
kind: "fleet-mining";
profile: string;
}
| {
address: string;
amount: string;
authority: string;
configHash: string;
dataHash?: undefined;
describes: string;
game: string;
keyIndex: number;
kind: "fleet-add-ship";
maximumProfileDebit: string;
profile: string;
shipId: number;
system: string;
}
| {
address: string;
authority: string;
currencyCache: string;
dataHash?: undefined;
describes: string;
game: string;
keyIndex: number;
kind: "research-unlock";
level: number;
maximumAtlasDebit: string;
maximumProfileDebit: string;
nodeId: number;
profile: string;
researchSequenceId: number;
starbasePlayer: string;
system: string;
xpSequenceId: number;
}
| {
address: string;
authority: string;
dataHash?: undefined;
describes: string;
kind: "profile-storage-funding";
maximumProfileDebit: string;
profile: string;
}
| {
address: string;
authority: string;
authorityHash: string;
character: string;
dataHash?: undefined;
describes: string;
fleet: string;
game: string;
keyIndex: number;
kind: "scan-signal-open";
maximumProfileDebit: string;
profile: string;
}
| {
address: string;
authority: string;
dataHash?: undefined;
describes: string;
game: string;
keyIndex: number;
kind: "fleet-create";
label: string;
maximumProfileDebit: string;
profile: string;
system: string;
}
| {
address: string;
cargoId: number;
dataHash?: undefined;
describes: string;
factionId: number;
floorRaw: string;
game: string;
kind: "faction-treasury-buy-versioned";
schemaVersion: number;
}
| {
address: string;
atlasOutCapPerEpochRaw: string;
dataHash?: undefined;
describes: string;
epochLengthSeconds: string;
factionId: number;
game: string;
kind: "faction-treasury-sell-versioned";
schemaVersion: number;
}
| {
address: string;
dataHash?: undefined;
describes: string;
factionId: number;
game: string;
kind: "faction-epoch-meter-versioned";
schemaVersion: number;
}
| {
address: string;
dataHash?: undefined;
describes: string;
kind: "system-account-or-absent";
}
| {
address: string;
dataHash?: undefined;
decimals: number;
describes: string;
kind: "token-mint";
}
| {
address: string;
configHash: string;
dataHash?: undefined;
describes: string;
kind: "recipe-state";
requiredUses: string;
}
| {
address: string;
dataHash: string;
describes: string;
kind: "account-state";
}
| {
address: string;
dataHash?: undefined;
describes: string;
kind: "account-absent";
}
| {
address: string;
dataHash?: undefined;
describes: string;
kind: "token-account-or-absent";
mint: string;
owner: string;
}
| {
address: string;
dataHash?: undefined;
describes: string;
kind: "token-account";
minimumBalance: string;
mint: string;
owner: string;
}
| {
address: string;
cargoId: number;
configHash: string;
dataHash?: undefined;
describes: string;
kind: "game-cargo-bytes-config";
}
| {
address: string;
bump: number;
dataHash?: undefined;
describes: string;
game: string;
kind: "cargo-cache";
}
| {
address: string;
configHash: string;
dataHash?: undefined;
describes: string;
kind: "game-ship-config";
shipId: number;
}
| {
address: string;
dataHash?: undefined;
describes: string;
kind: "game-account";
}
| RuntimeWire)[];
```
Defined in: [packages/sage/src/planning/index.ts:457](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L457)
##### requiredSigners
```ts
readonly requiredSigners: readonly string[];
```
Defined in: [packages/sage/src/planning/index.ts:464](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L464)
##### 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:443](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L443)
##### summary
```ts
readonly summary: string;
```
Defined in: [packages/sage/src/planning/index.ts:442](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L442)
##### v
```ts
readonly v: 32;
```
Defined in: [packages/sage/src/planning/index.ts:440](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L440)
***
### 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
##### 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)
##### 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)
##### 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)
##### 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)
##### 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
##### 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`[]
***
### PlanSequenceCheckpointV1
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)
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 };
const checkpoint: PlanSequenceCheckpointV1 = createPlanSequenceCheckpoint(
sequence,
'2026-08-28T12:00:00.000Z',
);
await callerOwnedStore.save(stringifyPlanSequenceCheckpoint(checkpoint));
```
#### Properties
##### attempt?
```ts
readonly optional attempt?: PlanSequenceCheckpointAttemptV1;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:103](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L103)
##### cluster
```ts
readonly cluster: ClusterIdentity;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:97](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L97)
##### confirmed
```ts
readonly confirmed: readonly PlanSequenceConfirmedStepV1[];
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:102](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L102)
##### fingerprint
```ts
readonly fingerprint: PlanSequenceFingerprint;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:96](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L96)
##### nextStepIndex
```ts
readonly nextStepIndex: number;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:101](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L101)
##### observedAt
```ts
readonly observedAt: string;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:104](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L104)
##### revision
```ts
readonly revision: number;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:99](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L99)
##### sequenceId
```ts
readonly sequenceId: string;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:98](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L98)
##### stepIds
```ts
readonly stepIds: readonly string[];
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:100](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L100)
##### v
```ts
readonly v: 1;
```
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)
***
### 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
##### 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)
##### 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)
##### 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)
##### 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)
##### 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)
***
### PlanSequencePresentation
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:63](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L63)
Fresh single-transaction authorization detail presented before signing.
#### Example
```ts
declare const presentation: PlanSequencePresentation;
console.log(presentation.stepId, presentation.description);
```
#### Properties
##### description
```ts
readonly description: readonly string[];
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:67](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L67)
##### index
```ts
readonly index: number;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:65](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L65)
##### plan
```ts
readonly plan: Plan;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:66](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L66)
##### stepId
```ts
readonly stepId: string;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:64](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L64)
***
### 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
##### 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
##### prepare()
```ts
prepare(context): Promise;
```
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)\>
***
### PlanSequenceStore
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:51](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L51)
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
##### save()
```ts
save(checkpoint): Promise;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:52](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L52)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `checkpoint` | [`PlanSequenceCheckpointV1`](/reference/planning/#plansequencecheckpointv1) |
###### Returns
`Promise`\<`void`\>
***
### PlanStep
Defined in: [packages/sage/src/planning/index.ts:102](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L102)
One ordered instruction and its game-language signer requirements.
#### Example
```ts
declare const step: PlanStep;
console.log(step.describes, step.signers);
```
#### Properties
##### describes
```ts
readonly describes: string;
```
Defined in: [packages/sage/src/planning/index.ts:104](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L104)
##### instruction
```ts
readonly instruction: Instruction[]>;
```
Defined in: [packages/sage/src/planning/index.ts:103](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L103)
##### semantics?
```ts
readonly optional semantics?: readonly PlanSemanticFact[];
```
Defined in: [packages/sage/src/planning/index.ts:105](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L105)
##### signers
```ts
readonly signers: readonly Address[];
```
Defined in: [packages/sage/src/planning/index.ts:106](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L106)
***
### SimulationOptions
Defined in: [packages/sage/src/planning/simulation.ts:35](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L35)
Optional RPC constraints for one unsigned simulation, not assembly overrides.
The SDK accepts the full u64 range. Kit's default RPC transport only encodes
integers through 9007199254740991; larger floors require a capable custom
transport. Never round or lower a required floor merely to encode it.
#### Example
```ts
const options: SimulationOptions = { minContextSlot: 53_000_000n };
```
#### Properties
##### minContextSlot?
```ts
readonly optional minContextSlot?: bigint;
```
Defined in: [packages/sage/src/planning/simulation.ts:37](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L37)
Inclusive node context floor, from zero through the unsigned 64-bit maximum.
***
### SimulationResult
Defined in: [packages/sage/src/planning/simulation.ts:171](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L171)
Node-provenance result from simulating one unsigned Plan.
#### Example
```ts
declare const result: SimulationResult;
console.log(result.slot, result.replacementBlockhash.blockhash);
```
#### Properties
##### logs
```ts
readonly logs: readonly string[];
```
Defined in: [packages/sage/src/planning/simulation.ts:174](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L174)
##### replacementBlockhash
```ts
readonly replacementBlockhash: Readonly<{
blockhash: string;
lastValidBlockHeight: bigint;
}>;
```
Defined in: [packages/sage/src/planning/simulation.ts:176](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L176)
##### returnData?
```ts
readonly optional returnData?: SimulationReturnData;
```
Defined in: [packages/sage/src/planning/simulation.ts:175](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L175)
##### slot
```ts
readonly slot: bigint;
```
Defined in: [packages/sage/src/planning/simulation.ts:172](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L172)
##### unitsConsumed
```ts
readonly unitsConsumed: bigint | undefined;
```
Defined in: [packages/sage/src/planning/simulation.ts:173](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L173)
***
### SimulationReturnData
Defined in: [packages/sage/src/planning/simulation.ts:158](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L158)
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
##### data
```ts
readonly data: string;
```
Defined in: [packages/sage/src/planning/simulation.ts:160](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L160)
##### programAddress
```ts
readonly programAddress: Address;
```
Defined in: [packages/sage/src/planning/simulation.ts:159](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L159)
## Type Aliases
### 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);
```
***
### PlanExecutionResult
```ts
type PlanExecutionResult =
| ConfirmedPlanExecution
| UnknownPlanExecution;
```
Defined in: [packages/sage/src/planning/execution.ts:215](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L215)
Every non-throwing terminal outcome from `executePlan`.
#### Example
```ts
declare const result: PlanExecutionResult;
if (result.status === 'unknown') console.log(result.signature);
```
***
### PlanPrecondition
```ts
type PlanPrecondition =
| FleetDockFundingGuard
| LocalMarketOrderGuard
| FleetCrewGuard
| ScanDetectGuard
| ScanCompletionGuard
| RuntimeGuard
| FleetAttackGuard
| FleetArrivalGuard
| {
address: Address;
authority: Address;
dataHash?: never;
describes: string;
fleetHash: string;
game: Address;
keyIndex: number;
kind: "fleet-respawn";
maximumProfileDebit: bigint;
maximumRecoveryFee: bigint;
phase: "start" | "complete";
profile: Address;
system: Address;
}
| {
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "currency-cache";
}
| {
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "movement-character";
profile: Address;
stateHash: string;
}
| {
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "fleet-docking-policy";
ownership: Address;
starbasePlayer: Address;
system: Address;
}
| {
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "starbase-system";
requireCss?: true;
starbaseSequenceId: bigint;
}
| {
address: Address;
budgetLamports: bigint;
characterLamports: bigint;
characterSize: number;
dataHash?: never;
describes: string;
funder: Address;
game: Address;
initializationHash: string;
kind: "character-registration";
maximumFunderDebit: bigint;
profile: Address;
profileDataHash: string;
xpBudget: Address;
xpBudgetConfig: Address;
}
| {
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "ship-import-funding";
maximumProfileDebit: bigint;
profile: Address;
shipId: number;
system: Address;
}
| {
address: Address;
asteroid: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "fleet-mining";
profile: Address;
}
| {
address: Address;
amount: bigint;
authority: Address;
configHash: string;
dataHash?: never;
describes: string;
game: Address;
keyIndex: number;
kind: "fleet-add-ship";
maximumProfileDebit: bigint;
profile: Address;
shipId: number;
system: Address;
}
| {
address: Address;
authority: Address;
currencyCache: Address;
dataHash?: never;
describes: string;
game: Address;
keyIndex: number;
kind: "research-unlock";
level: number;
maximumAtlasDebit: bigint;
maximumProfileDebit: bigint;
nodeId: number;
profile: Address;
researchSequenceId: number;
starbasePlayer: Address;
system: Address;
xpSequenceId: number;
}
| {
address: Address;
authority: Address;
dataHash?: never;
describes: string;
kind: "profile-storage-funding";
maximumProfileDebit: bigint;
profile: Address;
}
| OpenSignalGuard
| {
address: Address;
authority: Address;
dataHash?: never;
describes: string;
game: Address;
keyIndex: number;
kind: "fleet-create";
label: string;
maximumProfileDebit: bigint;
profile: Address;
system: Address;
}
| {
address: Address;
cargoId: number;
dataHash?: never;
describes: string;
factionId: number;
floorRaw: bigint;
game: Address;
kind: "faction-treasury-buy-versioned";
schemaVersion: number;
}
| {
address: Address;
atlasOutCapPerEpochRaw: bigint;
dataHash?: never;
describes: string;
epochLengthSeconds: bigint;
factionId: number;
game: Address;
kind: "faction-treasury-sell-versioned";
schemaVersion: number;
}
| {
address: Address;
dataHash?: never;
describes: string;
factionId: number;
game: Address;
kind: "faction-epoch-meter-versioned";
schemaVersion: number;
}
| {
address: Address;
dataHash?: never;
describes: string;
kind: "system-account-or-absent";
}
| {
address: Address;
dataHash?: never;
decimals: number;
describes: string;
kind: "token-mint";
}
| {
address: Address;
configHash: string;
dataHash?: never;
describes: string;
kind: "recipe-state";
requiredUses: bigint;
}
| {
address: Address;
dataHash: string;
describes: string;
kind: "account-state";
}
| {
address: Address;
dataHash?: never;
describes: string;
kind: "account-absent";
}
| {
address: Address;
dataHash?: never;
describes: string;
kind: "token-account-or-absent";
mint: Address;
owner: Address;
}
| {
address: Address;
dataHash?: never;
describes: string;
kind: "token-account";
minimumBalance: bigint;
mint: Address;
owner: Address;
}
| {
address: Address;
cargoId: number;
configHash: string;
dataHash?: never;
describes: string;
kind: "game-cargo-bytes-config";
}
| {
address: Address;
bump: number;
dataHash?: never;
describes: string;
game: Address;
kind: "cargo-cache";
}
| {
address: Address;
configHash: string;
dataHash?: never;
describes: string;
kind: "game-ship-config";
shipId: number;
}
| {
address: Address;
dataHash?: never;
describes: string;
kind: "game-account";
};
```
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 closure-free account freshness guard recorded at planning time.
#### Union Members
`FleetDockFundingGuard`
***
`LocalMarketOrderGuard`
***
`FleetCrewGuard`
***
`ScanDetectGuard`
***
`ScanCompletionGuard`
***
`RuntimeGuard`
***
`FleetAttackGuard`
***
`FleetArrivalGuard`
***
##### Type Literal
```ts
{
address: Address;
authority: Address;
dataHash?: never;
describes: string;
fleetHash: string;
game: Address;
keyIndex: number;
kind: "fleet-respawn";
maximumProfileDebit: bigint;
maximumRecoveryFee: bigint;
phase: "start" | "complete";
profile: Address;
system: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### authority
```ts
readonly authority: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### fleetHash
```ts
readonly fleetHash: string;
```
###### game
```ts
readonly game: Address;
```
###### keyIndex
```ts
readonly keyIndex: number;
```
###### kind
```ts
readonly kind: "fleet-respawn";
```
Standalone player-initiated recovery with observed ATLAS and Profile funding ceilings.
###### maximumProfileDebit
```ts
readonly maximumProfileDebit: bigint;
```
###### maximumRecoveryFee
```ts
readonly maximumRecoveryFee: bigint;
```
###### phase
```ts
readonly phase: "start" | "complete";
```
###### profile
```ts
readonly profile: Address;
```
###### system
```ts
readonly system: Address;
```
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "currency-cache";
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "currency-cache";
```
Canonical CurrencyCache identity; shared vault/withdrawal accounting may change.
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "movement-character";
profile: Address;
stateHash: string;
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "movement-character";
```
Canonical movement Character; earned XP accrual may change but other state remains bound.
###### profile
```ts
readonly profile: Address;
```
###### stateHash
```ts
readonly stateHash: string;
```
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "fleet-docking-policy";
ownership: Address;
starbasePlayer: Address;
system: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "fleet-docking-policy";
```
Docking admission: the canonical Game tracker, System ownership and
docking Starbase Player. Execution reads the Starbase owner,
generation and Starbase Player faction from fresh account data.
###### ownership
```ts
readonly ownership: Address;
```
###### starbasePlayer
```ts
readonly starbasePlayer: Address;
```
###### system
```ts
readonly system: Address;
```
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "starbase-system";
requireCss?: true;
starbaseSequenceId: bigint;
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "starbase-system";
```
Canonical System with an active Starbase in the expected generation; unrelated activity may change.
###### requireCss?
```ts
readonly optional requireCss?: true;
```
Required by wallet deposits and ship imports; cancellation/withdrawal allow any active Starbase.
###### starbaseSequenceId
```ts
readonly starbaseSequenceId: bigint;
```
***
##### Type Literal
```ts
{
address: Address;
budgetLamports: bigint;
characterLamports: bigint;
characterSize: number;
dataHash?: never;
describes: string;
funder: Address;
game: Address;
initializationHash: string;
kind: "character-registration";
maximumFunderDebit: bigint;
profile: Address;
profileDataHash: string;
xpBudget: Address;
xpBudgetConfig: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### budgetLamports
```ts
readonly budgetLamports: bigint;
```
###### characterLamports
```ts
readonly characterLamports: bigint;
```
###### characterSize
```ts
readonly characterSize: number;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### funder
```ts
readonly funder: Address;
```
###### game
```ts
readonly game: Address;
```
###### initializationHash
```ts
readonly initializationHash: string;
```
###### kind
```ts
readonly kind: "character-registration";
```
Exact current-runtime Character and Career XP creation with capped wallet funding.
###### maximumFunderDebit
```ts
readonly maximumFunderDebit: bigint;
```
###### profile
```ts
readonly profile: Address;
```
###### profileDataHash
```ts
readonly profileDataHash: string;
```
###### xpBudget
```ts
readonly xpBudget: Address;
```
###### xpBudgetConfig
```ts
readonly xpBudgetConfig: Address;
```
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "ship-import-funding";
maximumProfileDebit: bigint;
profile: Address;
shipId: number;
system: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "ship-import-funding";
```
Fresh Profile reserve and capped storage funding for one imported ship configuration.
###### maximumProfileDebit
```ts
readonly maximumProfileDebit: bigint;
```
###### profile
```ts
readonly profile: Address;
```
###### shipId
```ts
readonly shipId: number;
```
###### system
```ts
readonly system: Address;
```
***
##### Type Literal
```ts
{
address: Address;
asteroid: Address;
dataHash?: never;
describes: string;
game: Address;
kind: "fleet-mining";
profile: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### asteroid
```ts
readonly asteroid: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "fleet-mining";
```
Fleet identity and active mining target must still match before signing.
###### profile
```ts
readonly profile: Address;
```
***
##### Type Literal
```ts
{
address: Address;
amount: bigint;
authority: Address;
configHash: string;
dataHash?: never;
describes: string;
game: Address;
keyIndex: number;
kind: "fleet-add-ship";
maximumProfileDebit: bigint;
profile: Address;
shipId: number;
system: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### amount
```ts
readonly amount: bigint;
```
###### authority
```ts
readonly authority: Address;
```
###### configHash
```ts
readonly configHash: string;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### keyIndex
```ts
readonly keyIndex: number;
```
###### kind
```ts
readonly kind: "fleet-add-ship";
```
Exact ship assembly intent; eligibility and capped Profile rent funding are rechecked before signing.
###### maximumProfileDebit
```ts
readonly maximumProfileDebit: bigint;
```
###### profile
```ts
readonly profile: Address;
```
###### shipId
```ts
readonly shipId: number;
```
###### system
```ts
readonly system: Address;
```
***
##### Type Literal
```ts
{
address: Address;
authority: Address;
currencyCache: Address;
dataHash?: never;
describes: string;
game: Address;
keyIndex: number;
kind: "research-unlock";
level: number;
maximumAtlasDebit: bigint;
maximumProfileDebit: bigint;
nodeId: number;
profile: Address;
researchSequenceId: number;
starbasePlayer: Address;
system: Address;
xpSequenceId: number;
}
```
###### address
```ts
readonly address: Address;
```
The canonical Character that pays and receives the node.
###### authority
```ts
readonly authority: Address;
```
###### currencyCache
```ts
readonly currencyCache: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### keyIndex
```ts
readonly keyIndex: number;
```
###### kind
```ts
readonly kind: "research-unlock";
```
Exact next level of one research node; eligibility, costs and the ATLAS debit ceiling are rechecked before signing.
###### level
```ts
readonly level: number;
```
The level the node reaches; the current stored level plus one.
###### maximumAtlasDebit
```ts
readonly maximumAtlasDebit: bigint;
```
Exact observed ATLAS Floyd debit; execution rejects a higher cost.
###### maximumProfileDebit
```ts
readonly maximumProfileDebit: bigint;
```
Conservative Profile lamport debit for Character and Starbase Player storage; execution rejects a higher debit.
###### nodeId
```ts
readonly nodeId: number;
```
###### profile
```ts
readonly profile: Address;
```
###### researchSequenceId
```ts
readonly researchSequenceId: number;
```
###### starbasePlayer
```ts
readonly starbasePlayer: Address;
```
###### system
```ts
readonly system: Address;
```
###### xpSequenceId
```ts
readonly xpSequenceId: number;
```
***
##### Type Literal
```ts
{
address: Address;
authority: Address;
dataHash?: never;
describes: string;
kind: "profile-storage-funding";
maximumProfileDebit: bigint;
profile: Address;
}
```
###### address
```ts
readonly address: Address;
```
The first account the action resizes.
###### authority
```ts
readonly authority: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "profile-storage-funding";
```
Account storage one action funds from the Profile vault. Execution rederives what the action resizes from its instruction and fresh accounts, then rechecks the debit ceiling, signing key and Profile balance before signing.
###### maximumProfileDebit
```ts
readonly maximumProfileDebit: bigint;
```
Planned Profile lamport debit; execution rejects a higher debit.
###### profile
```ts
readonly profile: Address;
```
***
`OpenSignalGuard`
***
##### Type Literal
```ts
{
address: Address;
authority: Address;
dataHash?: never;
describes: string;
game: Address;
keyIndex: number;
kind: "fleet-create";
label: string;
maximumProfileDebit: bigint;
profile: Address;
system: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### authority
```ts
readonly authority: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### game
```ts
readonly game: Address;
```
###### keyIndex
```ts
readonly keyIndex: number;
```
###### kind
```ts
readonly kind: "fleet-create";
```
Exact creation intent; required eligibility is revalidated with a capped Profile debit.
###### label
```ts
readonly label: string;
```
###### maximumProfileDebit
```ts
readonly maximumProfileDebit: bigint;
```
###### profile
```ts
readonly profile: Address;
```
###### system
```ts
readonly system: Address;
```
***
##### Type Literal
```ts
{
address: Address;
cargoId: number;
dataHash?: never;
describes: string;
factionId: number;
floorRaw: bigint;
game: Address;
kind: "faction-treasury-buy-versioned";
schemaVersion: number;
}
```
###### address
```ts
readonly address: Address;
```
###### cargoId
```ts
readonly cargoId: number;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### factionId
```ts
readonly factionId: number;
```
###### floorRaw
```ts
readonly floorRaw: bigint;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "faction-treasury-buy-versioned";
```
Canonical Treasury and selected cargo floor; live stock may change.
###### schemaVersion
```ts
readonly schemaVersion: number;
```
Observed account schema byte; not an activity counter.
***
##### Type Literal
```ts
{
address: Address;
atlasOutCapPerEpochRaw: bigint;
dataHash?: never;
describes: string;
epochLengthSeconds: bigint;
factionId: number;
game: Address;
kind: "faction-treasury-sell-versioned";
schemaVersion: number;
}
```
###### address
```ts
readonly address: Address;
```
###### atlasOutCapPerEpochRaw
```ts
readonly atlasOutCapPerEpochRaw: bigint;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### epochLengthSeconds
```ts
readonly epochLengthSeconds: bigint;
```
###### factionId
```ts
readonly factionId: number;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "faction-treasury-sell-versioned";
```
Canonical Treasury payout rules; vault and epoch activity may change.
###### schemaVersion
```ts
readonly schemaVersion: number;
```
Observed account schema byte; not an activity counter.
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
factionId: number;
game: Address;
kind: "faction-epoch-meter-versioned";
schemaVersion: number;
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### factionId
```ts
readonly factionId: number;
```
###### game
```ts
readonly game: Address;
```
###### kind
```ts
readonly kind: "faction-epoch-meter-versioned";
```
Canonical aggregate meter; epoch and accrual counters may change.
###### schemaVersion
```ts
readonly schemaVersion: number;
```
Observed account schema byte; not an activity counter.
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
kind: "system-account-or-absent";
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "system-account-or-absent";
```
Absent wallet or an empty, non-executable System account; native funding may change.
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
decimals: number;
describes: string;
kind: "token-mint";
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### decimals
```ts
readonly decimals: number;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "token-mint";
```
Initialized original Token Mint with unchanged decimals; supply and authorities may change.
***
##### Type Literal
```ts
{
address: Address;
configHash: string;
dataHash?: never;
describes: string;
kind: "recipe-state";
requiredUses: bigint;
}
```
###### address
```ts
readonly address: Address;
```
###### configHash
```ts
readonly configHash: string;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "recipe-state";
```
Recipe configuration excluding concurrent usage; starts require remaining uses.
###### requiredUses
```ts
readonly requiredUses: bigint;
```
***
##### Type Literal
```ts
{
address: Address;
dataHash: string;
describes: string;
kind: "account-state";
}
```
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
kind: "account-absent";
}
```
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
kind: "token-account-or-absent";
mint: Address;
owner: Address;
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "token-account-or-absent";
```
Tolerates concurrent idempotent creation of a matching original Token account.
###### mint
```ts
readonly mint: Address;
```
###### owner
```ts
readonly owner: Address;
```
Token authority, distinct from the fixed original Token program owner.
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
kind: "token-account";
minimumBalance: bigint;
mint: Address;
owner: Address;
}
```
***
##### Type Literal
```ts
{
address: Address;
cargoId: number;
configHash: string;
dataHash?: never;
describes: string;
kind: "game-cargo-bytes-config";
}
```
###### address
```ts
readonly address: Address;
```
###### cargoId
```ts
readonly cargoId: number;
```
###### configHash
```ts
readonly configHash: string;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "game-cargo-bytes-config";
```
The selected pinned cargo encoding and cache address remain identical.
***
##### Type Literal
```ts
{
address: Address;
bump: number;
dataHash?: never;
describes: string;
game: Address;
kind: "cargo-cache";
}
```
***
##### Type Literal
```ts
{
address: Address;
configHash: string;
dataHash?: never;
describes: string;
kind: "game-ship-config";
shipId: number;
}
```
###### address
```ts
readonly address: Address;
```
###### configHash
```ts
readonly configHash: string;
```
SHA-256 of the owner and complete pinned Ship encoding.
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "game-ship-config";
```
The selected ship configuration remains identical.
###### shipId
```ts
readonly shipId: number;
```
Explicit unsigned 16-bit configuration ID in this Game.
***
##### Type Literal
```ts
{
address: Address;
dataHash?: never;
describes: string;
kind: "game-account";
}
```
###### address
```ts
readonly address: Address;
```
###### dataHash?
```ts
readonly optional dataHash?: never;
```
###### describes
```ts
readonly describes: string;
```
###### kind
```ts
readonly kind: "game-account";
```
Existing non-executable C4 Game with a valid complete layout; no definition equality check.
#### Example
```ts
declare const precondition: PlanPrecondition;
console.log(precondition.address, precondition.kind);
```
***
### 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:71](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L71)
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',
};
```
***
### PlanSequenceCheckpointAttemptV1
```ts
type PlanSequenceCheckpointAttemptV1 =
| Readonly<{
index: number;
phase: "prepared";
signerMode: "observable" | "opaque";
stepId: string;
}>
| Readonly<{
index: number;
lifetime?: | Readonly<{
contextSlot: string;
lastValidBlockHeight: string;
}>
| null;
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:49](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L49)
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.
Protect checkpoint integrity: recovery trusts its RPC-sourced lifetime
metadata. Missing lifetime evidence never establishes expiry.
#### Example
```ts
declare const attempt: PlanSequenceCheckpointAttemptV1;
console.log(attempt.stepId, attempt.phase);
```
***
### 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';
```
***
### 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
```
***
### 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';
```
***
### 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());
```
***
### PlanSequenceResult
```ts
type PlanSequenceResult =
| 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:217](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L217)
Finite safe result envelope for future checkpoint-backed coordination.
The checkpoint codec supplies the generic checkpoint value. Raw errors,
signers and callback values are never fields. Signed checkpoints may retain
RPC-sourced lifetime metadata for recovery during resume.
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);
```
***
### 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';
```
***
### 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';
```
***
### 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);
```
***
### 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:184](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L184)
A submitted transaction whose terminal state remains unknown.
#### Example
```ts
declare const result: UnknownPlanExecution;
console.log(result.signature, result.lastValidBlockHeight);
```
## Functions
### assemblePlan()
```ts
function assemblePlan(
context,
plan,
policy): Promise & TransactionWithBlockhashLifetime>;
```
Defined in: [packages/sage/src/planning/assembly.ts:279](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/assembly.ts#L279)
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 });
```
***
### combinePlans()
```ts
function combinePlans(...plans): Plan;
```
Defined in: [packages/sage/src/planning/index.ts:892](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L892)
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);
```
***
### confirmPlanSequenceCheckpointStep()
```ts
function confirmPlanSequenceCheckpointStep(
checkpoint,
evidence,
observedAt): PlanSequenceCheckpointV1;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:746](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L746)
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',
);
```
***
### createPlan()
```ts
function createPlan(input): Plan;
```
Defined in: [packages/sage/src/planning/index.ts:682](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L682)
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);
```
***
### createPlanSequence()
```ts
function createPlanSequence(input): Promise;
```
Defined in: [packages/sage/src/planning/plan-sequence.ts:596](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence.ts#L596)
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());
```
***
### createPlanSequenceCheckpoint()
```ts
function createPlanSequenceCheckpoint(sequence, observedAt): 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)
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
```
***
### executePlan()
```ts
function executePlan(
context,
plan,
options): Promise;
```
Defined in: [packages/sage/src/planning/execution.ts:1791](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/execution.ts#L1791)
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);
```
***
### executePlanSequence()
```ts
function executePlanSequence(
context,
sequence,
checkpointSource,
options): Promise;
```
Defined in: [packages/sage/src/planning/plan-sequence-execution.ts:413](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-execution.ts#L413)
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.
Resume can continue after confirmed success. Confirmed failure or expiry stops
with the existing transaction code and unchanged attempt. Expiry assumes a
trusted, complete and healthy RPC history index; optional getEpochInfo and
getFirstAvailableBlock checks detect stale/pruned evidence, not missing index
entries. Insufficient evidence stays SEQUENCE_ATTEMPT_UNRESOLVED.
#### 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);
```
***
### parsePlanSequenceCheckpoint()
```ts
function parsePlanSequenceCheckpoint(sequence, source): PlanSequenceCheckpointV1;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:566](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L566)
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);
```
***
### planFromJSON()
```ts
function planFromJSON(json): Plan;
```
Defined in: [packages/sage/src/planning/index.ts:759](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/index.ts#L759)
Rehydrates and validates a complete versioned Plan wire value.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `json` | `unknown` |
#### Returns
[`Plan`](/reference/planning/#plan)
#### Example
```ts
declare const wire: PlanJson;
const plan = planFromJSON(wire);
console.log(plan.describe());
```
***
### setPlanSequenceCheckpointAttempt()
```ts
function setPlanSequenceCheckpointAttempt(
checkpoint,
attempt,
observedAt): PlanSequenceCheckpointV1;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:678](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L678)
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',
);
```
***
### simulatePlan()
```ts
function simulatePlan(
context,
plan,
policy,
options?): Promise;
```
Defined in: [packages/sage/src/planning/simulation.ts:225](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/simulation.ts#L225)
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.
Optional minContextSlot constrains only this simulation RPC. An unavailable
floor rejects once without retry or fallback. The returned slot remains the
node's value; callers may separately enforce a defensive returned-slot check
on successful results only. Simulation failures do not expose a context slot.
The SDK accepts full-u64 floors, but Kit's default transport encodes only
through 9007199254740991; larger floors need a capable custom transport.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `plan` | [`Plan`](/reference/planning/#plan) |
| `policy` | [`AssemblyPolicy`](/reference/planning/#assemblypolicy) |
| `options?` | [`SimulationOptions`](/reference/planning/#simulationoptions) |
#### 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);
const minimum = 53_000_000n;
const fresh = await simulatePlan(ctx, plan, { feePayer }, { minContextSlot: minimum });
if (fresh.slot < minimum) throw new Error('Simulation returned an older context.');
```
***
### stringifyPlanSequenceCheckpoint()
```ts
function stringifyPlanSequenceCheckpoint(checkpoint): string;
```
Defined in: [packages/sage/src/planning/plan-sequence-checkpoint.ts:830](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/planning/plan-sequence-checkpoint.ts#L830)
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 };
const storedJson = stringifyPlanSequenceCheckpoint(checkpoint);
await callerOwnedStore.save(storedJson);
```