# cargo/actions
Documentation: next (source: develop).

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

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

## Interfaces

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

### PlanAuthorization

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

Address-only authorization retained by planning before execution binds signers.

#### Example

```ts
declare const profile: Address;
declare const authority: Address;
const authorization: PlanAuthorization = {
  profile,
  authority,
  keyIndex: 0,
};
```

#### Properties

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

##### authority

```ts
readonly authority: Address;
```

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

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

##### certificate?

```ts
readonly optional certificate?: Address;
```

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

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

##### keyIndex

```ts
readonly keyIndex: number;
```

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

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

##### profile

```ts
readonly profile: Address;
```

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

***

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

### PlanFleetTransferCargoAtStarbaseOptions

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

Inputs for one explicit Fleet/player-Starbase cargo transfer.

Every quantity is a positive raw on-chain `bigint`. Ammo and fuel are bounded
by signed i64 because direction is encoded by sign; cargo-hold quantities use
unsigned u64 and cargo ids use unsigned u16.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetTransferCargoAtStarbaseOptions = {
  authorization,
  direction: 'toFleet',
  amounts: {
    ammo: 25n,
    cargoHold: [{ cargoId: 3, amount: 2n }],
  },
};
```

#### Properties

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

##### amounts

```ts
readonly amounts: {
  ammo?: bigint;
  cargoHold?: readonly {
     amount: bigint;
     cargoId: number;
  }[];
  fuel?: bigint;
};
```

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

###### ammo?

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

###### cargoHold?

```ts
readonly optional cargoHold?: readonly {
  amount: bigint;
  cargoId: number;
}[];
```

###### fuel?

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

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

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

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

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

##### direction

```ts
readonly direction: "toFleet" | "toStarbase";
```

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

***

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

### PlanFleetTransferCargoWithinFleetOptions

Defined in: [packages/sage/src/cargo/actions/index.ts:90](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/cargo/actions/index.ts#L90)

Inputs for moving one exact cargo quantity between two pods in one Fleet.

The amount is a positive raw on-chain unsigned-u64 `bigint`; the cargo id is
an unsigned-u16 integer. Pod names select the Fleet snapshot's nested ammo,
fuel, or cargo-hold inventory without accepting CargoPod account addresses.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetTransferCargoWithinFleetOptions = {
  amount: 5n,
  authorization,
  cargoId: 2,
  from: 'ammo',
  to: 'cargoHold',
};
```

#### Properties

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

##### amount

```ts
readonly amount: bigint;
```

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

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

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

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

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

##### cargoId

```ts
readonly cargoId: number;
```

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

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

##### from

```ts
readonly from: "cargoHold" | "fuel" | "ammo";
```

Defined in: [packages/sage/src/cargo/actions/index.ts:92](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/cargo/actions/index.ts#L92)

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

##### to

```ts
readonly to: "cargoHold" | "fuel" | "ammo";
```

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

## Functions

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

### planFleetTransferCargoAtStarbase()

```ts
function planFleetTransferCargoAtStarbase(
   ctx, 
   fleet, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/cargo/actions/index.ts:600](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/cargo/actions/index.ts#L600)

Plans one bidirectional Fleet/player-Starbase cargo transfer without signing or RPC writes.

The caller supplies only gameplay direction and positive raw-unit quantities.
Planning directly re-reads the Fleet, canonical Character, and derived
StarbasePlayer; checks known source balances (aggregated by cargo id for the
shared Starbase inventory) and, when loading the Fleet, exact
ammo/fuel/cargo capacity; and returns one inspectable instruction. The chain
remains authoritative for state races, crew normalization, faction
policy, Profile permission bits including `MANAGE_FLEET_CARGO`, and program
arithmetic. Starbase destination capacity is not inferred because the
shipped StarbasePlayer read exposes no total-capacity field.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `FleetSnapshot` |
| `input` | [`PlanFleetTransferCargoAtStarbaseOptions`](/reference/cargo/actions/#planfleettransfercargoatstarbaseoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetTransferCargoAtStarbase(ctx, fleet, {
  authorization,
  direction: 'toStarbase',
  amounts: { fuel: 10n },
});
console.log(plan.describe());
```

***

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

### planFleetTransferCargoWithinFleet()

```ts
function planFleetTransferCargoWithinFleet(
   ctx, 
   fleet, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/cargo/actions/index.ts:972](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/cargo/actions/index.ts#L972)

Plans one exact cargo transfer between two nested pods in one Fleet.

The caller supplies pod names, one unsigned-u16 cargo id, and one positive
raw unsigned-u64 amount. Planning uses only the supplied Fleet snapshot for
pod identities, resolved cargo ids, balances, and ammo/fuel/cargo-hold
capacity. It accepts idle, docked, and Claim Stake transfer states and
returns one signer-free, inspectable instruction. The chain remains
authoritative for state races, Profile permission bits including
`MANAGE_FLEET_CARGO`, and program arithmetic.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `FleetSnapshot` |
| `input` | [`PlanFleetTransferCargoWithinFleetOptions`](/reference/cargo/actions/#planfleettransfercargowithinfleetoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetTransferCargoWithinFleet(ctx, fleet, {
  amount: 5n,
  authorization,
  cargoId: fleet.ammo.id,
  from: 'ammo',
  to: 'cargoHold',
});
console.log(plan.describe());
```