# Saving data for later

[Programming guides](README.md)

Storage lets a program remember data for later. **Persistent** or **durable** data can remain after a run ends; **ephemeral** data lasts only for the session. A **snapshot** is a copy of the value at the moment it is saved. A **quota** is the maximum amount you may store. The [JSON explanation](../concepts/json.md) introduces the kinds of values accepted below.

| English call | Canonical ID | Returns | Requirements |
|---|---|---|---|
| `saveData(key, value)` | `storage.set` | `None` | A valid Text key and [JSON-compatible](../concepts/json.md) value. |
| `loadData(key, fallback)` | `storage.get` | saved value or fallback | A valid Text key; the fallback may be any JSON-compatible value. |
| `deleteData(key)` | `storage.delete` | `Boolean` | A valid Text key. |
| `savedDataKeys()` | `storage.keys` | `List<Text>` | No arguments. |

Saved values may be `none`, finite numbers, text, Booleans, lists, and maps
with text keys. A key is not a path or filename: it must be non-empty text,
without surrounding whitespace or control characters, and no longer than 128
[UTF-8](../concepts/utf-8.md) bytes. `saveData` captures a snapshot; `loadData` returns a fresh copy,
including when it returns the fallback. `savedDataKeys()` uses deterministic
UTF-8 byte ordering.

These calls are intentionally small and host-mediated. A portable project with
a usable identity can retain its own bounded data across normal saves; a plain
or not-yet-migrated source file receives fresh ephemeral data. See the
[saved-data specification](../../../docs/spec/storage.md).

## Reading the storage limits

A **node** here is one part of a saved value, such as a list, a map, or a value inside it. **Nesting** means putting collections inside other collections, like boxes inside boxes; the nesting limit bounds how many layers you may use.

**KiB** means kibibyte: 1,024 bytes. Thus 64 KiB is 65,536 bytes, not necessarily that many letters. [UTF-8](../concepts/utf-8.md) explains why a letter or emoji can use several bytes.

A **schema** is the agreed structure of a saved document; its version tells Pliro which structure to expect. **Migration** updates an older project structure. An application's **identity** tells the host which private store belongs to that project. **Atomic replacement** means a write succeeds as one whole replacement or leaves the previous data intact; a failed write must not leave half the new document. **Deterministic order** means the same keys sort in the same way each time; byte ordering is a computer ordering rule, not necessarily dictionary order.

## Behavior and details

A usable schema-3 .bipli identity owns its data [namespace](../concepts/modules.md). Normal Save, move, and rename preserve it; Save As, Duplicate, and Import as copy create a separate identity. Loose sources and unmigrated projects use temporary session storage.

Limits: 128 keys; 64 KiB per JSON value; 512 KiB for the complete document; 32 nesting levels and 8,192 values/nodes per value. Failed writes preserve previous data. E4014 means unavailable storage, E4015 an invalid key, E4016 an incompatible value, and E4017 an exceeded quota. Remote preview renders desktop execution and does not receive private data.

## Related entries

[Syntax and values](../syntax/README.md) · [Built-ins](../builtins/README.md) · [Programming guides](README.md)