planning

Interfaces

AssemblyPolicy

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

Policy for assembling an unsigned transaction from one Plan.

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

computeUnitLimit?

readonly optional computeUnitLimit?: number;

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

feePayer

readonly feePayer: Address;

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

priorityFeeMicroLamports?

readonly optional priorityFeeMicroLamports?: bigint;

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

ConfirmedPlanExecution

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

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

signature

readonly signature: Signature;

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

slot

readonly slot: bigint;

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

status

readonly status: "confirmed";

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

CreatePlanInput

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

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

preconditions

readonly preconditions: readonly PlanPrecondition[];

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

steps

readonly steps: readonly PlanStep[];

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

summary

readonly summary: string;

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

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

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

computeUnitLimit?

readonly optional computeUnitLimit?: number;

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

feePayer

readonly feePayer: TransactionSigner;

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

pollIntervalMs?

readonly optional pollIntervalMs?: number;

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

priorityFeeMicroLamports?

readonly optional priorityFeeMicroLamports?: bigint;

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

signers?

readonly optional signers?: readonly TransactionSigner[];

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

timeoutMs?

readonly optional timeoutMs?: number;

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

ExecutePlanSequenceOptions

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

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

computeUnitLimit?

readonly optional computeUnitLimit?: number;

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

Inherited from

ExecutePlanOptions.computeUnitLimit

feePayer

readonly feePayer: TransactionSigner;

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

Inherited from

ExecutePlanOptions.feePayer

onBeforeSign?

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

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

Parameters

Parameter	Type
`presentation`	`PlanSequencePresentation`

Returns

Promise<void>

pollIntervalMs?

readonly optional pollIntervalMs?: number;

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

Inherited from

ExecutePlanOptions.pollIntervalMs

priorityFeeMicroLamports?

readonly optional priorityFeeMicroLamports?: bigint;

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

Inherited from

ExecutePlanOptions.priorityFeeMicroLamports

signal?

readonly optional signal?: AbortSignal;

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

signers?

readonly optional signers?: readonly TransactionSigner[];

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

Inherited from

ExecutePlanOptions.signers

store

readonly store: PlanSequenceStore;

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

timeoutMs?

readonly optional timeoutMs?: number;

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

Inherited from

ExecutePlanOptions.timeoutMs

Plan

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

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

affected

readonly affected: readonly Address[];

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

kind

readonly kind: string;

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

preconditions

readonly preconditions: readonly PlanPrecondition[];

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

requiredSigners

readonly requiredSigners: readonly Address[];

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

steps

readonly steps: readonly PlanStep[];

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

summary

readonly summary: string;

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

Methods

describe()

describe(): readonly string[];

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

Returns

readonly string[]

toJSON()

toJSON():
  | PlanJsonV1
  | PlanJsonV2;

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

Returns

| PlanJsonV1 | PlanJsonV2

PlanJsonV1

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

The complete persistent wire representation of a Plan.

Example

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

Properties

affected

readonly affected: readonly string[];

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

kind

readonly kind: string;

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

preconditions

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

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

requiredSigners

readonly requiredSigners: readonly string[];

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

steps

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

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

summary

readonly summary: string;

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

v

readonly v: 1;

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

PlanJsonV2

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

The version-two Plan wire representation for semantic-bearing steps.

Version two retains every version-one top-level field and adds optional normalized semantic facts to individual steps.

Example

declare const plan: Plan;
const wire: PlanJsonV1 | PlanJsonV2 = plan.toJSON();
if (wire.v === 2) console.log(wire.steps[0]?.semantics);

Properties

affected

readonly affected: readonly string[];

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

kind

readonly kind: string;

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

preconditions

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

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

requiredSigners

readonly requiredSigners: readonly string[];

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

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

summary

readonly summary: string;

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

v

readonly v: 2;

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

PlanPrecondition

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

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

Example

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

Properties

address

readonly address: Address;

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

dataHash

readonly dataHash: string;

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

describes

readonly describes: string;

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

kind

readonly kind: "account-state";

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

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

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

cluster

readonly cluster: ClusterIdentity;

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

confirmed

readonly confirmed: readonly PlanSequenceConfirmedStepV1[];

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

fingerprint

readonly fingerprint: PlanSequenceFingerprint;

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

nextStepIndex

readonly nextStepIndex: number;

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

observedAt

readonly observedAt: string;

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

revision

readonly revision: number;

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

sequenceId

readonly sequenceId: string;

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

stepIds

readonly stepIds: readonly string[];

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

v

readonly v: 1;

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

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

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

index

readonly index: number;

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

plan

readonly plan: Plan;

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

stepId

readonly stepId: string;

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

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

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

Parameters

Parameter	Type
`checkpoint`	`PlanSequenceCheckpointV1`

Returns

Promise<void>

PlanStep

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

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

instruction

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

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

semantics?

readonly optional semantics?: readonly PlanSemanticFact[];

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

signers

readonly signers: readonly Address[];

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

SimulationResult

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

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

replacementBlockhash

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

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

returnData?

readonly optional returnData?: SimulationReturnData;

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

slot

readonly slot: bigint;

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

unitsConsumed

readonly unitsConsumed: bigint | undefined;

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

SimulationReturnData

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

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

programAddress

readonly programAddress: Address;

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

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

Every non-throwing terminal outcome from executePlan.

Example

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

PlanSemanticFact

type PlanSemanticFact =
  | {
  fact: string;
  kind: "requires";
  resource: string;
}
  | {
  fact: string;
  kind: "invalidates";
  resource: string;
}
  | {
  from: string;
  kind: "transition";
  resource: string;
  to: string;
};

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

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.

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;
  phase: "signed";
  signature: Signature;
  signerMode: "observable";
  stepId: string;
}>
  | Readonly<{
  index: number;
  phase: "invoking";
  signerMode: "opaque";
  stepId: string;
}>;

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

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

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

Example

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

Finite safe result envelope for future checkpoint-backed coordination.

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

Type Parameters

Type Parameter	Default type
`Checkpoint`	`unknown`

Example

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

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

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

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

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

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

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 step: PlanSequenceStep;
const sequence = await createPlanSequence({
  cluster: 'zink-ptr',
  sequenceId: 'fleet-round-trip',
  revision: 0,
  steps: [step],
});
console.log(sequence.fingerprint);

createPlanSequenceCheckpoint()

function createPlanSequenceCheckpoint(sequence, observedAt): PlanSequenceCheckpointV1;

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

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

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

Executes or resumes one PlanSequence invocation without polling or retrying.

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

Parameters

Parameter	Type
`context`	`SageContext`
`sequence`	`PlanSequence`
`checkpointSource`	`unknown`
`options`	`ExecutePlanSequenceOptions`

Returns

Promise<SequenceResult>

Example

declare const ctx: SageContext;
declare const sequence: PlanSequence;
declare const checkpointJson: string;
declare const options: ExecutePlanSequenceOptions;
const result = await executePlanSequence(ctx, sequence, checkpointJson, options);
console.log(result.status, result.checkpoint.nextStepIndex);

parsePlanSequenceCheckpoint()

function parsePlanSequenceCheckpoint(sequence, source): PlanSequenceCheckpointV1;

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

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

Rehydrates and validates a complete versioned Plan wire value.

Parameters

Parameter	Type
`json`	`unknown`

Returns

Plan

Example

declare const wire: PlanJsonV1 | PlanJsonV2;
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:649

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): Promise<SimulationResult>;

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

Simulates one Plan without receiving or invoking a signer.

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

Parameters

Parameter	Type
`context`	`SageContext`
`plan`	`Plan`
`policy`	`AssemblyPolicy`

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

stringifyPlanSequenceCheckpoint()

function stringifyPlanSequenceCheckpoint(checkpoint): string;

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

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