GenoGlobe
Learning from Life

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<!DOCTYPE markdown>
# ARR Load Policy (APS)

This document defines the **ARR loading policy** for APS (Ardule Pattern Studio).
It specifies how a source ARR is applied to the currently edited chain (target),
including chain entries, sections, and metadata handling.

---

## 0. Terminology

- **target**  
  The pattern chain currently being edited in APS.

- **source**  
  The ARR file being loaded.

- **ins**  
  The insertion index in the target chain (cursor position or append point).

- **m**  
  Number of chain entries in the source ARR.

- **section**  
  A metadata range attached to the chain, defined by start–end indices.

---

## 1. Core Principles

1. ARR loading is treated as **inserting or appending** the source chain into the target chain.
2. The chain itself is a **linear time axis** without implicit loops.
3. Sections are **metadata only** and must not break the chain structure.
4. ARR loading should **always succeed if possible**; conflicts are resolved by
   renaming and offsetting, not by rejection or silent overwrite.

---

## 2. Chain Entry Handling

- Source chain entries are inserted into the target chain while preserving:
  - order
  - repeat counts
  - referenced pattern filenames **as-is**

### 2.1 Filename integrity (P/B/H suffix)

APS treats the referenced pattern filename as an **opaque identifier** during ARR load.
In particular, suffix conventions such as:

- `_P###` (pattern)
- `_B###` (break)
- `_h###` (half / 1-bar playback hint; _H is supported for backward compatibility)

MUST be preserved exactly as they appear in the source ARR.
ARR loading MUST NOT rewrite these suffixes, normalize them, or edit the referenced ADT files.

> Note: Actual 1-bar playback behavior is determined at playback time by the ADT load policy
> (e.g., `PLAY_BARS=1` in the ADT header, with `_H###` as a fallback hint).

### 2.2 Insertion positions

- **Insert**: at index `ins`
- **Append**: at `len(target)`

---

## 3. Target Section Handling (Split Rule)

Existing sections in the target are processed relative to the insertion point `ins`.

### 3.1 Sections Completely Before the Insertion Point

Condition:
```
section.end < ins
```

- No changes are applied.

---

### 3.2 Sections Covering the Insertion Point (Split)

Condition:
```
section.start < ins <= section.end
```

Given an original section:
```
S = [a .. b]
```

It is replaced by two sections:

- **Left section**
  - Name: `S_L`
  - Range: `[a .. ins - 1]`

- **Right section**
  - Name: `S_R`
  - Range: `[ins + m .. b + m]`

The original section `S` is removed.

---

### 3.3 Sections Completely After the Insertion Point

Condition:
```
section.start >= ins
```

- Apply offset `+m` to both start and end.
- Section name is preserved.

---

## 4. Source Section Handling (Import Rule)

All sections defined in the source ARR are imported into the target.

### 4.1 Name Prefix

- Every source section name is prefixed with:
```
i_
```

Examples:
- `Verse` → `i_Verse`
- `Chorus` → `i_Chorus`

This prefix unconditionally marks imported sections.

---

### 4.2 Range Offset

- Source section ranges are offset by the insertion index `ins`.

---

### 4.3 Name Uniqueness

- Semantic name conflicts are **not checked**.
- If an identical name already exists, a numeric suffix is appended:
  - `i_Verse`, `i_Verse2`, `i_Verse3`, ...

This guarantees uniqueness without merging semantics.

---

## 5. #PLAY Handling

- `#PLAY` in the source ARR is treated as **metadata**.
- Default behavior:
  - Target playback behavior is **not modified**.
- Optional behavior:
  - The `#PLAY` position may be stored with offset applied, as a reference hint.

---

## 6. Validation and Error Handling

- Missing pattern files referenced by the source:
  - Loading proceeds.
  - Existing runtime warning mechanisms are used during playback.
- Invalid or out-of-range section definitions:
  - The affected sections are ignored.
  - Loading continues.

---

## 7. Policy Summary

> ARR loading applies the source chain to the target chain via insertion or append.  
> Target sections crossing the insertion point are split into `_L` and `_R`.  
> Source sections are imported with an `i_` prefix and offset ranges.  
> Section conflicts are resolved by renaming, not merging.  
> Pattern filenames (including P/B/H suffixes) are preserved as-is during load.  
> The chain load operation should succeed whenever possible.

---

_Last updated: 2026-01-03_