planning

Interfaces

AssemblyPolicy

Defined in: packages/sage/src/planning/assembly.ts:52

Policy for assembling an unsigned transaction from one Plan.

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

Example

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

Properties

commitment?

readonly optional commitment?: Commitment;

Defined in: packages/sage/src/planning/assembly.ts:56

computeUnitLimit?

readonly optional computeUnitLimit?: number;

Defined in: packages/sage/src/planning/assembly.ts:54

feePayer

readonly feePayer: Address;

Defined in: packages/sage/src/planning/assembly.ts:53

priorityFeeMicroLamports?

readonly optional priorityFeeMicroLamports?: bigint;

Defined in: packages/sage/src/planning/assembly.ts:55

ConfirmedPlanExecution

Defined in: packages/sage/src/planning/execution.ts:169

A transaction confirmed at the requested commitment.

Example

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

Properties

commitment

readonly commitment: Commitment;

Defined in: packages/sage/src/planning/execution.ts:173

signature

readonly signature: Signature;

Defined in: packages/sage/src/planning/execution.ts:171

slot

readonly slot: bigint;

Defined in: packages/sage/src/planning/execution.ts:172

status

readonly status: "confirmed";

Defined in: packages/sage/src/planning/execution.ts:170

CreatePlanInput

Defined in: packages/sage/src/planning/index.ts:504

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

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

Properties

kind

readonly kind: string;

Defined in: packages/sage/src/planning/index.ts:505

preconditions

readonly preconditions: readonly PlanPrecondition[];

Defined in: packages/sage/src/planning/index.ts:508

steps

readonly steps: readonly PlanStep[];

Defined in: packages/sage/src/planning/index.ts:507

summary

readonly summary: string;

Defined in: packages/sage/src/planning/index.ts:506

CreatePlanSequenceInput

Defined in: packages/sage/src/planning/plan-sequence.ts:111

Exact caller-owned input accepted by createPlanSequence.

Example

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

Properties

cluster

readonly cluster: ClusterIdentity;

Defined in: packages/sage/src/planning/plan-sequence.ts:112

revision

readonly revision: number;

Defined in: packages/sage/src/planning/plan-sequence.ts:114

sequenceId

readonly sequenceId: string;

Defined in: packages/sage/src/planning/plan-sequence.ts:113

steps

readonly steps: readonly PlanSequenceStep[];

Defined in: packages/sage/src/planning/plan-sequence.ts:115

ExecutePlanOptions

Defined in: packages/sage/src/planning/execution.ts:151

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

Example

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

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

Properties

commitment?

readonly optional commitment?: Commitment;

Defined in: packages/sage/src/planning/execution.ts:156

computeUnitLimit?

readonly optional computeUnitLimit?: number;

Defined in: packages/sage/src/planning/execution.ts:154

feePayer

readonly feePayer: TransactionSigner;

Defined in: packages/sage/src/planning/execution.ts:152

pollIntervalMs?

readonly optional pollIntervalMs?: number;

Defined in: packages/sage/src/planning/execution.ts:158

priorityFeeMicroLamports?

readonly optional priorityFeeMicroLamports?: bigint;

Defined in: packages/sage/src/planning/execution.ts:155

signers?

readonly optional signers?: readonly TransactionSigner[];

Defined in: packages/sage/src/planning/execution.ts:153

timeoutMs?

readonly optional timeoutMs?: number;

Defined in: packages/sage/src/planning/execution.ts:157

ExecutePlanSequenceOptions

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:82

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

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

Extends

Omit<ExecutePlanOptions, "commitment">

Properties

commitment?

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

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:86

computeUnitLimit?

readonly optional computeUnitLimit?: number;

Defined in: packages/sage/src/planning/execution.ts:154

Inherited from

ExecutePlanOptions.computeUnitLimit

feePayer

readonly feePayer: TransactionSigner;

Defined in: packages/sage/src/planning/execution.ts:152

Inherited from

ExecutePlanOptions.feePayer

onBeforeSign?

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

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:89

Parameters

Parameter	Type
`presentation`	`PlanSequencePresentation`

Returns

Promise<void>

pollIntervalMs?

readonly optional pollIntervalMs?: number;

Defined in: packages/sage/src/planning/execution.ts:158

Inherited from

ExecutePlanOptions.pollIntervalMs

priorityFeeMicroLamports?

readonly optional priorityFeeMicroLamports?: bigint;

Defined in: packages/sage/src/planning/execution.ts:155

Inherited from

ExecutePlanOptions.priorityFeeMicroLamports

signal?

readonly optional signal?: AbortSignal;

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:88

signers?

readonly optional signers?: readonly TransactionSigner[];

Defined in: packages/sage/src/planning/execution.ts:153

Inherited from

ExecutePlanOptions.signers

store

readonly store: PlanSequenceStore;

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:87

timeoutMs?

readonly optional timeoutMs?: number;

Defined in: packages/sage/src/planning/execution.ts:157

Inherited from

ExecutePlanOptions.timeoutMs

Plan

Defined in: packages/sage/src/planning/index.ts:476

Inert, inspectable action data built only through planning factories.

Example

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

Properties

[PLAN_BRAND]

readonly [PLAN_BRAND]: true;

Defined in: packages/sage/src/planning/index.ts:485

affected

readonly affected: readonly Address[];

Defined in: packages/sage/src/planning/index.ts:481

kind

readonly kind: string;

Defined in: packages/sage/src/planning/index.ts:477

preconditions

readonly preconditions: readonly PlanPrecondition[];

Defined in: packages/sage/src/planning/index.ts:480

requiredSigners

readonly requiredSigners: readonly Address[];

Defined in: packages/sage/src/planning/index.ts:482

steps

readonly steps: readonly PlanStep[];

Defined in: packages/sage/src/planning/index.ts:479

summary

readonly summary: string;

Defined in: packages/sage/src/planning/index.ts:478

Methods

describe()

describe(): readonly string[];

Defined in: packages/sage/src/planning/index.ts:483

Returns

readonly string[]

toJSON()

toJSON(): PlanJson;

Defined in: packages/sage/src/planning/index.ts:484

Returns

PlanJson

PlanJson

Defined in: packages/sage/src/planning/index.ts:439

The current persistent Plan format. Unsupported versions require a fresh Plan.

Example

declare const plan: Plan;
const wire: PlanJson = plan.toJSON();
console.log(wire.v);
const restored = planFromJSON(wire);

Properties

affected

readonly affected: readonly string[];

Defined in: packages/sage/src/planning/index.ts:463

kind

readonly kind: string;

Defined in: packages/sage/src/planning/index.ts:441

preconditions

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<LocalMarketOrderGuard>)[];

Defined in: packages/sage/src/planning/index.ts:457

requiredSigners

readonly requiredSigners: readonly string[];

Defined in: packages/sage/src/planning/index.ts:464

steps

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

summary

readonly summary: string;

Defined in: packages/sage/src/planning/index.ts:442

v

readonly v: 32;

Defined in: packages/sage/src/planning/index.ts:440

PlanSequence

Defined in: packages/sage/src/planning/plan-sequence.ts:129

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

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

Properties

cluster

readonly cluster: ClusterIdentity;

Defined in: packages/sage/src/planning/plan-sequence.ts:130

fingerprint

readonly fingerprint: PlanSequenceFingerprint;

Defined in: packages/sage/src/planning/plan-sequence.ts:134

revision

readonly revision: number;

Defined in: packages/sage/src/planning/plan-sequence.ts:132

sequenceId

readonly sequenceId: string;

Defined in: packages/sage/src/planning/plan-sequence.ts:131

steps

readonly steps: readonly PlanSequenceStep[];

Defined in: packages/sage/src/planning/plan-sequence.ts:133

Methods

describe()

describe(): readonly string[];

Defined in: packages/sage/src/planning/plan-sequence.ts:135

Returns

readonly string[]

PlanSequenceCheckpointV1

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:94

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

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

attempt?

readonly optional attempt?: PlanSequenceCheckpointAttemptV1;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:103

cluster

readonly cluster: ClusterIdentity;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:97

confirmed

readonly confirmed: readonly PlanSequenceConfirmedStepV1[];

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:102

fingerprint

readonly fingerprint: PlanSequenceFingerprint;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:96

nextStepIndex

readonly nextStepIndex: number;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:101

observedAt

readonly observedAt: string;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:104

revision

readonly revision: number;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:99

sequenceId

readonly sequenceId: string;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:98

stepIds

readonly stepIds: readonly string[];

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:100

v

readonly v: 1;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:95

PlanSequenceConfirmedStepV1

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:28

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

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

Properties

commitment

readonly commitment: "confirmed" | "finalized";

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:33

index

readonly index: number;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:30

signature

readonly signature: Signature;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:31

slot

readonly slot: string;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:32

stepId

readonly stepId: string;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:29

PlanSequencePresentation

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:63

Fresh single-transaction authorization detail presented before signing.

Example

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

Properties

description

readonly description: readonly string[];

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:67

index

readonly index: number;

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:65

plan

readonly plan: Plan;

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:66

stepId

readonly stepId: string;

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:64

PlanSequenceStep

Defined in: packages/sage/src/planning/plan-sequence.ts:93

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

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

Properties

id

readonly id: string;

Defined in: packages/sage/src/planning/plan-sequence.ts:94

Methods

prepare()

prepare(context): Promise<PlanSequenceReadiness>;

Defined in: packages/sage/src/planning/plan-sequence.ts:95

Parameters

Parameter	Type
`context`	`PlanSequenceStepContext`

Returns

Promise<PlanSequenceReadiness>

PlanSequenceStore

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:51

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

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

Methods

save()

save(checkpoint): Promise<void>;

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:52

Parameters

Parameter	Type
`checkpoint`	`PlanSequenceCheckpointV1`

Returns

Promise<void>

PlanStep

Defined in: packages/sage/src/planning/index.ts:102

One ordered instruction and its game-language signer requirements.

Example

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

Properties

describes

readonly describes: string;

Defined in: packages/sage/src/planning/index.ts:104

instruction

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

Defined in: packages/sage/src/planning/index.ts:103

semantics?

readonly optional semantics?: readonly PlanSemanticFact[];

Defined in: packages/sage/src/planning/index.ts:105

signers

readonly signers: readonly Address[];

Defined in: packages/sage/src/planning/index.ts:106

SimulationOptions

Defined in: packages/sage/src/planning/simulation.ts:35

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

const options: SimulationOptions = { minContextSlot: 53_000_000n };

Properties

minContextSlot?

readonly optional minContextSlot?: bigint;

Defined in: packages/sage/src/planning/simulation.ts:37

Inclusive node context floor, from zero through the unsigned 64-bit maximum.

SimulationResult

Defined in: packages/sage/src/planning/simulation.ts:171

Node-provenance result from simulating one unsigned Plan.

Example

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

Properties

logs

readonly logs: readonly string[];

Defined in: packages/sage/src/planning/simulation.ts:174

replacementBlockhash

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

Defined in: packages/sage/src/planning/simulation.ts:176

returnData?

readonly optional returnData?: SimulationReturnData;

Defined in: packages/sage/src/planning/simulation.ts:175

slot

readonly slot: bigint;

Defined in: packages/sage/src/planning/simulation.ts:172

unitsConsumed

readonly unitsConsumed: bigint | undefined;

Defined in: packages/sage/src/planning/simulation.ts:173

SimulationReturnData

Defined in: packages/sage/src/planning/simulation.ts:158

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

Example

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

Properties

data

readonly data: string;

Defined in: packages/sage/src/planning/simulation.ts:160

programAddress

readonly programAddress: Address;

Defined in: packages/sage/src/planning/simulation.ts:159

Type Aliases

ConfirmedStep

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

Defined in: packages/sage/src/planning/plan-sequence.ts:37

Public confirmation evidence available to later lazy step preparation.

Example

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

PlanExecutionResult

type PlanExecutionResult =
  | ConfirmedPlanExecution
  | UnknownPlanExecution;

Defined in: packages/sage/src/planning/execution.ts:215

Every non-throwing terminal outcome from executePlan.

Example

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

PlanPrecondition

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

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

Union Members

FleetDockFundingGuard

LocalMarketOrderGuard

FleetCrewGuard

ScanDetectGuard

ScanCompletionGuard

RuntimeGuard

FleetAttackGuard

FleetArrivalGuard

Type Literal

{
  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

readonly address: Address;

authority

readonly authority: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

fleetHash

readonly fleetHash: string;

game

readonly game: Address;

keyIndex

readonly keyIndex: number;

kind

readonly kind: "fleet-respawn";

Standalone player-initiated recovery with observed ATLAS and Profile funding ceilings.

maximumProfileDebit

readonly maximumProfileDebit: bigint;

maximumRecoveryFee

readonly maximumRecoveryFee: bigint;

phase

readonly phase: "start" | "complete";

profile

readonly profile: Address;

system

readonly system: Address;

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "currency-cache";
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

kind

readonly kind: "currency-cache";

Canonical CurrencyCache identity; shared vault/withdrawal accounting may change.

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "movement-character";
  profile: Address;
  stateHash: string;
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

kind

readonly kind: "movement-character";

Canonical movement Character; earned XP accrual may change but other state remains bound.

profile

readonly profile: Address;

stateHash

readonly stateHash: string;

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "fleet-docking-policy";
  ownership: Address;
  starbasePlayer: Address;
  system: Address;
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

kind

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

readonly ownership: Address;

starbasePlayer

readonly starbasePlayer: Address;

system

readonly system: Address;

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "starbase-system";
  requireCss?: true;
  starbaseSequenceId: bigint;
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

kind

readonly kind: "starbase-system";

Canonical System with an active Starbase in the expected generation; unrelated activity may change.

requireCss?

readonly optional requireCss?: true;

Required by wallet deposits and ship imports; cancellation/withdrawal allow any active Starbase.

starbaseSequenceId

readonly starbaseSequenceId: bigint;

Type Literal

{
  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

readonly address: Address;

budgetLamports

readonly budgetLamports: bigint;

characterLamports

readonly characterLamports: bigint;

characterSize

readonly characterSize: number;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

funder

readonly funder: Address;

game

readonly game: Address;

initializationHash

readonly initializationHash: string;

kind

readonly kind: "character-registration";

Exact current-runtime Character and Career XP creation with capped wallet funding.

maximumFunderDebit

readonly maximumFunderDebit: bigint;

profile

readonly profile: Address;

profileDataHash

readonly profileDataHash: string;

xpBudget

readonly xpBudget: Address;

xpBudgetConfig

readonly xpBudgetConfig: Address;

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "ship-import-funding";
  maximumProfileDebit: bigint;
  profile: Address;
  shipId: number;
  system: Address;
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

kind

readonly kind: "ship-import-funding";

Fresh Profile reserve and capped storage funding for one imported ship configuration.

maximumProfileDebit

readonly maximumProfileDebit: bigint;

profile

readonly profile: Address;

shipId

readonly shipId: number;

system

readonly system: Address;

Type Literal

{
  address: Address;
  asteroid: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "fleet-mining";
  profile: Address;
}

address

readonly address: Address;

asteroid

readonly asteroid: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

kind

readonly kind: "fleet-mining";

Fleet identity and active mining target must still match before signing.

profile

readonly profile: Address;

Type Literal

{
  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

readonly address: Address;

amount

readonly amount: bigint;

authority

readonly authority: Address;

configHash

readonly configHash: string;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

keyIndex

readonly keyIndex: number;

kind

readonly kind: "fleet-add-ship";

Exact ship assembly intent; eligibility and capped Profile rent funding are rechecked before signing.

maximumProfileDebit

readonly maximumProfileDebit: bigint;

profile

readonly profile: Address;

shipId

readonly shipId: number;

system

readonly system: Address;

Type Literal

{
  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

readonly address: Address;

The canonical Character that pays and receives the node.

authority

readonly authority: Address;

currencyCache

readonly currencyCache: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

keyIndex

readonly keyIndex: number;

kind

readonly kind: "research-unlock";

Exact next level of one research node; eligibility, costs and the ATLAS debit ceiling are rechecked before signing.

level

readonly level: number;

The level the node reaches; the current stored level plus one.

maximumAtlasDebit

readonly maximumAtlasDebit: bigint;

Exact observed ATLAS Floyd debit; execution rejects a higher cost.

maximumProfileDebit

readonly maximumProfileDebit: bigint;

Conservative Profile lamport debit for Character and Starbase Player storage; execution rejects a higher debit.

nodeId

readonly nodeId: number;

profile

readonly profile: Address;

researchSequenceId

readonly researchSequenceId: number;

starbasePlayer

readonly starbasePlayer: Address;

system

readonly system: Address;

xpSequenceId

readonly xpSequenceId: number;

Type Literal

{
  address: Address;
  authority: Address;
  dataHash?: never;
  describes: string;
  kind: "profile-storage-funding";
  maximumProfileDebit: bigint;
  profile: Address;
}

address

readonly address: Address;

The first account the action resizes.

authority

readonly authority: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

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

readonly maximumProfileDebit: bigint;

Planned Profile lamport debit; execution rejects a higher debit.

profile

readonly profile: Address;

OpenSignalGuard

Type Literal

{
  address: Address;
  authority: Address;
  dataHash?: never;
  describes: string;
  game: Address;
  keyIndex: number;
  kind: "fleet-create";
  label: string;
  maximumProfileDebit: bigint;
  profile: Address;
  system: Address;
}

address

readonly address: Address;

authority

readonly authority: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

game

readonly game: Address;

keyIndex

readonly keyIndex: number;

kind

readonly kind: "fleet-create";

Exact creation intent; required eligibility is revalidated with a capped Profile debit.

label

readonly label: string;

maximumProfileDebit

readonly maximumProfileDebit: bigint;

profile

readonly profile: Address;

system

readonly system: Address;

Type Literal

{
  address: Address;
  cargoId: number;
  dataHash?: never;
  describes: string;
  factionId: number;
  floorRaw: bigint;
  game: Address;
  kind: "faction-treasury-buy-versioned";
  schemaVersion: number;
}

address

readonly address: Address;

cargoId

readonly cargoId: number;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

factionId

readonly factionId: number;

floorRaw

readonly floorRaw: bigint;

game

readonly game: Address;

kind

readonly kind: "faction-treasury-buy-versioned";

Canonical Treasury and selected cargo floor; live stock may change.

schemaVersion

readonly schemaVersion: number;

Observed account schema byte; not an activity counter.

Type Literal

{
  address: Address;
  atlasOutCapPerEpochRaw: bigint;
  dataHash?: never;
  describes: string;
  epochLengthSeconds: bigint;
  factionId: number;
  game: Address;
  kind: "faction-treasury-sell-versioned";
  schemaVersion: number;
}

address

readonly address: Address;

atlasOutCapPerEpochRaw

readonly atlasOutCapPerEpochRaw: bigint;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

epochLengthSeconds

readonly epochLengthSeconds: bigint;

factionId

readonly factionId: number;

game

readonly game: Address;

kind

readonly kind: "faction-treasury-sell-versioned";

Canonical Treasury payout rules; vault and epoch activity may change.

schemaVersion

readonly schemaVersion: number;

Observed account schema byte; not an activity counter.

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  factionId: number;
  game: Address;
  kind: "faction-epoch-meter-versioned";
  schemaVersion: number;
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

factionId

readonly factionId: number;

game

readonly game: Address;

kind

readonly kind: "faction-epoch-meter-versioned";

Canonical aggregate meter; epoch and accrual counters may change.

schemaVersion

readonly schemaVersion: number;

Observed account schema byte; not an activity counter.

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  kind: "system-account-or-absent";
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

readonly kind: "system-account-or-absent";

Absent wallet or an empty, non-executable System account; native funding may change.

Type Literal

{
  address: Address;
  dataHash?: never;
  decimals: number;
  describes: string;
  kind: "token-mint";
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

decimals

readonly decimals: number;

describes

readonly describes: string;

kind

readonly kind: "token-mint";

Initialized original Token Mint with unchanged decimals; supply and authorities may change.

Type Literal

{
  address: Address;
  configHash: string;
  dataHash?: never;
  describes: string;
  kind: "recipe-state";
  requiredUses: bigint;
}

address

readonly address: Address;

configHash

readonly configHash: string;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

readonly kind: "recipe-state";

Recipe configuration excluding concurrent usage; starts require remaining uses.

requiredUses

readonly requiredUses: bigint;

Type Literal

{
  address: Address;
  dataHash: string;
  describes: string;
  kind: "account-state";
}

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  kind: "account-absent";
}

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  kind: "token-account-or-absent";
  mint: Address;
  owner: Address;
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

readonly kind: "token-account-or-absent";

Tolerates concurrent idempotent creation of a matching original Token account.

mint

readonly mint: Address;

owner

readonly owner: Address;

Token authority, distinct from the fixed original Token program owner.

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  kind: "token-account";
  minimumBalance: bigint;
  mint: Address;
  owner: Address;
}

Type Literal

{
  address: Address;
  cargoId: number;
  configHash: string;
  dataHash?: never;
  describes: string;
  kind: "game-cargo-bytes-config";
}

address

readonly address: Address;

cargoId

readonly cargoId: number;

configHash

readonly configHash: string;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

readonly kind: "game-cargo-bytes-config";

The selected pinned cargo encoding and cache address remain identical.

Type Literal

{
  address: Address;
  bump: number;
  dataHash?: never;
  describes: string;
  game: Address;
  kind: "cargo-cache";
}

Type Literal

{
  address: Address;
  configHash: string;
  dataHash?: never;
  describes: string;
  kind: "game-ship-config";
  shipId: number;
}

address

readonly address: Address;

configHash

readonly configHash: string;

SHA-256 of the owner and complete pinned Ship encoding.

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

readonly kind: "game-ship-config";

The selected ship configuration remains identical.

shipId

readonly shipId: number;

Explicit unsigned 16-bit configuration ID in this Game.

Type Literal

{
  address: Address;
  dataHash?: never;
  describes: string;
  kind: "game-account";
}

address

readonly address: Address;

dataHash?

readonly optional dataHash?: never;

describes

readonly describes: string;

kind

readonly kind: "game-account";

Existing non-executable C4 Game with a valid complete layout; no definition equality check.

Example

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

PlanSemanticFact

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

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

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

kind

readonly kind: "exclusive";

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

scope

readonly scope: "transaction";

Type Literal

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

Type Literal

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

Type Literal

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

Example

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

PlanSequenceCheckpointAttemptV1

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

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

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

PlanSequenceErrorCode

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

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

Example

const code: PlanSequenceErrorCode = 'SEQUENCE_PREPARATION_FAILED';

PlanSequenceFingerprint

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

Defined in: packages/sage/src/planning/plan-sequence.ts:25

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

Type Declaration

[PLAN_SEQUENCE_FINGERPRINT_BRAND]

readonly [PLAN_SEQUENCE_FINGERPRINT_BRAND]: true;

Example

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

PlanSequencePhase

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

Defined in: packages/sage/src/planning/plan-sequence.ts:165

Finite lifecycle phase safe to expose in a sequence result.

Example

const phase: PlanSequencePhase = 'preparing';

PlanSequenceReadiness

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

Defined in: packages/sage/src/planning/plan-sequence.ts:71

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

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

PlanSequenceResult

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:217

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

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

PlanSequenceResultCode

type PlanSequenceResultCode =
  | PlanSequenceErrorCode
  | SageSdkErrorCode;

Defined in: packages/sage/src/planning/plan-sequence.ts:200

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

const code: PlanSequenceResultCode = 'INVALID_ACTION_INPUT';

PlanSequenceStatus

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

Defined in: packages/sage/src/planning/plan-sequence.ts:155

Every public sequence coordination status.

completed is the only successful terminal status.

Example

const status: PlanSequenceStatus = 'waiting';

PlanSequenceStepContext

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

Defined in: packages/sage/src/planning/plan-sequence.ts:53

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

Example

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

UnknownPlanExecution

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

A submitted transaction whose terminal state remains unknown.

Example

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

Functions

assemblePlan()

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

Defined in: packages/sage/src/planning/assembly.ts:279

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`
`plan`	`Plan`
`policy`	`AssemblyPolicy`

Returns

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

Example

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

combinePlans()

function combinePlans(...plans): Plan;

Defined in: packages/sage/src/planning/index.ts:892

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`[]

Returns

Plan

Example

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

confirmPlanSequenceCheckpointStep()

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

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:746

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`
`evidence`	`ConfirmedStep`
`observedAt`	`string`

Returns

PlanSequenceCheckpointV1

Example

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

createPlan()

function createPlan(input): Plan;

Defined in: packages/sage/src/planning/index.ts:682

Creates an inert branded Plan while deriving every aggregate field.

Parameters

Parameter	Type
`input`	`CreatePlanInput`

Returns

Plan

Example

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

createPlanSequence()

function createPlanSequence(input): Promise<PlanSequence>;

Defined in: packages/sage/src/planning/plan-sequence.ts:596

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`

Returns

Promise<PlanSequence>

Example

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()

function createPlanSequenceCheckpoint(sequence, observedAt): PlanSequenceCheckpointV1;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:537

Creates an empty checkpoint bound to one exact Plan sequence.

Parameters

Parameter	Type
`sequence`	`PlanSequence`
`observedAt`	`string`

Returns

PlanSequenceCheckpointV1

Example

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

executePlan()

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

Defined in: packages/sage/src/planning/execution.ts:1791

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

Parameters

Parameter	Type
`context`	`SageContext`
`plan`	`Plan`
`options`	`ExecutePlanOptions`

Returns

Promise<PlanExecutionResult>

Example

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()

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

Defined in: packages/sage/src/planning/plan-sequence-execution.ts:413

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`
`sequence`	`PlanSequence`
`checkpointSource`	`unknown`
`options`	`ExecutePlanSequenceOptions`

Returns

Promise<SequenceResult>

Example

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()

function parsePlanSequenceCheckpoint(sequence, source): PlanSequenceCheckpointV1;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:566

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`
`source`	`unknown`

Returns

PlanSequenceCheckpointV1

Example

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

planFromJSON()

function planFromJSON(json): Plan;

Defined in: packages/sage/src/planning/index.ts:759

Rehydrates and validates a complete versioned Plan wire value.

Parameters

Parameter	Type
`json`	`unknown`

Returns

Plan

Example

declare const wire: PlanJson;
const plan = planFromJSON(wire);
console.log(plan.describe());

setPlanSequenceCheckpointAttempt()

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

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:678

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`
`attempt`	`PlanSequenceCheckpointAttemptV1`
`observedAt`	`string`

Returns

PlanSequenceCheckpointV1

Example

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()

function simulatePlan(
   context,
   plan,
   policy,
options?): Promise<SimulationResult>;

Defined in: packages/sage/src/planning/simulation.ts:225

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`
`plan`	`Plan`
`policy`	`AssemblyPolicy`
`options?`	`SimulationOptions`

Returns

Promise<SimulationResult>

Example

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()

function stringifyPlanSequenceCheckpoint(checkpoint): string;

Defined in: packages/sage/src/planning/plan-sequence-checkpoint.ts:830

Serializes one SDK-created checkpoint to canonical compact JSON.

Parameters

Parameter	Type
`checkpoint`	`PlanSequenceCheckpointV1`

Returns

string

Example

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