# scanning/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/scanning/actions/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

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

### PlanDetectSignalOptions

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

Explicit choices for one Idle Fleet's detection; setup and funding are separate.

#### Example

```ts
declare const profile: Address, authority: Address;
const authorization = { profile, authority, keyIndex: 0 };
const options: PlanDetectSignalOptions = { authorization, patternId: 0, focus: 'any' };
```

#### Extends

- `DetectOptions`

#### Properties

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

##### authorization

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

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

###### Inherited from

```ts
DetectOptions.authorization
```

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

##### focus

```ts
readonly focus: "any" | "industrial" | "technology" | "tactical" | "exotic";
```

Defined in: [packages/sage/src/internal/planning/scan-detect.ts:51](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/internal/planning/scan-detect.ts#L51)

###### Inherited from

```ts
DetectOptions.focus
```

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

##### patternId

```ts
readonly patternId: number;
```

Defined in: [packages/sage/src/internal/planning/scan-detect.ts:50](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/internal/planning/scan-detect.ts#L50)

###### Inherited from

```ts
DetectOptions.patternId
```

***

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

### PlanOpenScanSignalOptions

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

Explicit address-only direct Profile authorization for signal setup. Certificates are unsupported.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanOpenScanSignalOptions = { authorization };
```

#### Properties

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

##### authorization

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

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

***

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

### PlanScanCompletionOptions

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

Direct address-only authority for recovery, abandonment and receipt acknowledgement.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanScanCompletionOptions = { authorization };
```

#### Extends

- `ScanCompletionOptions`

#### Properties

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

##### authorization

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

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

###### Inherited from

```ts
ScanCompletionOptions.authorization
```

## Functions

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

### planAbandonSignal()

```ts
function planAbandonSignal(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

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

Abandon one unexpired Contact without attempting recovery. Acknowledgement remains a separate explicit action.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanScanCompletionOptions`](/reference/scanning/actions/#planscancompletionoptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address, options: PlanScanCompletionOptions;
const plan = await planAbandonSignal(ctx, fleet, options);
console.log(plan.describe());
```

***

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

### planAcknowledgeScanResult()

```ts
function planAcknowledgeScanResult(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

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

Clear one terminal receipt to Empty while retaining the funded signal. Explicitly includes the Fleet for current abandoned-receipt cooldown handling.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanScanCompletionOptions`](/reference/scanning/actions/#planscancompletionoptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address, options: PlanScanCompletionOptions;
const plan = await planAcknowledgeScanResult(ctx, fleet, options);
console.log(plan.describe());
```

***

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

### planDetectSignal()

```ts
function planDetectSignal(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

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

Plans one signal detection for an existing Empty signal and directly owned Idle Fleet.
Reads fresh prerequisites without signing. Restricted-key sufficiency, cooldown
rejection and final gameplay outcomes remain chain-authoritative; use simulatePlan.
No automatic opening, deposits, loading, undocking or resolution occurs.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanDetectSignalOptions`](/reference/scanning/actions/#plandetectsignaloptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address, options: PlanDetectSignalOptions;
const plan = await planDetectSignal(ctx, fleet, options);
console.log(plan.describe());
```

***

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

### planExpireSignal()

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

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

Expire one Contact after its deadline. No gameplay authority is needed; acknowledgement remains separate.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address;
const plan = await planExpireSignal(ctx, fleet);
console.log(plan.describe());
```

***

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

### planForfeitScanSignalEntropy()

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

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

Forfeit one PendingEntropy attempt after the supported reveal deadline. No gameplay authority is needed; acknowledgement remains separate.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address;
const plan = await planForfeitScanSignalEntropy(ctx, fleet);
console.log(plan.describe());
```

***

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

### planOpenScanSignal()

```ts
function planOpenScanSignal(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

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

Plans one absent canonical signal for a directly owned Fleet, including Docked Fleets.
Planning reads fresh state but never signs, submits, deposits funds or detects a signal.
The Profile funds signal rent while retaining its own reserve; transaction fees are separate.
Restricted-key least privilege is unqualified: instruction permission acceptance remains
chain-authoritative, and legacy SCAN bit 38 is not established as sufficient. Simulate before signing.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanOpenScanSignalOptions`](/reference/scanning/actions/#planopenscansignaloptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address, authorization: PlanAuthorization;
const plan = await planOpenScanSignal(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

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

### planRecoverSignal()

```ts
function planRecoverSignal(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

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

Recover one unexpired Contact with an Idle Fleet inside its stored radius. Cargo acceptance, clipping and XP remain chain-authoritative.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanScanCompletionOptions`](/reference/scanning/actions/#planscancompletionoptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address, options: PlanScanCompletionOptions;
const plan = await planRecoverSignal(ctx, fleet, options);
console.log(plan.describe());
```

***

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

### planResolveSignal()

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

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

Resolve one PendingEntropy signal using its committed policy and regional loot configuration. Requires current Character XP accounts; no gameplay authority is needed.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext, fleet: Address;
const plan = await planResolveSignal(ctx, fleet);
console.log(plan.describe());
```

## References

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

### PlanAuthorization

Re-exports [PlanAuthorization](/reference/cargo/actions/#planauthorization)