Prototype spec: storage (#12522)¶
Part of the agent-authored prototype specification.
A show resets state and data to the spec’s values, saved prototypes keep the spec and assets but
no user data, and the offline event buffer is lost if the process dies. A root-level storage block
names the values the device keeps for the prototype:
"storage": { "version": 1, "keys": ["state:darkMode", "data:/cart"] }
Secure state uses a separate Keystore-backed store. Its values are excluded from plaintext storage and its byte budget.
The capability is prototype_storage_v1 (PROTOTYPE_STORAGE_CAPABILITY). A show, or a patch whose
resulting spec contains storage, is refused on a device without it through the same gate registry
as every other capability (PROTOTYPE_SPEC_CAPABILITY_GATES, field storage).
Shape and validation. The block is strict: version is an integer from 1, keys holds 1 to
MAX_PROTOTYPE_STORAGE_KEYS (64) unique strings. The contract (schemas/prototype-spec-contract.json,
definition storage) checks the shape; prototypeStorageError (src/features/prototype/prototypeStorage.ts)
checks the rest, with the path of the first problem:
state:<key>: the key matches the state-key pattern and is declared in the spec’sstate.data:<pointer>: an RFC 6901 pointer to a member ofdata, validated withprototypeDataPathPointer(which wrapsisPrototypeDataPointer) on/data+ pointer, sodata:/cartis the path/data/cartthat data actions and patch ops use. The validator refuses the whole document (data:alone), a pointer without a leading/, or an over-long pointer. It also refuses two data pointers where one is the other’s ancestor or equal (/cartand/cart/items), so each stored value has one owner.- Duplicate keys are refused.
- The values the spec itself holds for the listed keys, counted per entry as the UTF-8 bytes of the
storage key plus the compact JSON of the value, must fit
MAX_PROTOTYPE_STORAGE_BYTES(262144).
| Constant | Value | Counting rule |
|---|---|---|
MAX_PROTOTYPE_STORAGE_BYTES |
262144 | Stored bytes per prototype id: sum over stored entries of key bytes + compact JSON bytes. |
MAX_PROTOTYPE_STORAGE_KEYS |
64 | Entries in storage.keys. |
What is stored. After every write the device saves the listed keys under the spec id. A write
is a user write (a tap, a text edit), a device data action (setData, appendData, prependData,
removeData) or a request response (#12523) that writes state or data. A write that would take
the stored total over MAX_PROTOTYPE_STORAGE_BYTES still applies on screen. The device does not
store it, the previous stored value of that key stays, and the inspect report lists the key in
skippedKeys. Stored values are part
of the device’s per-id state: they survive a dismiss, a process restart and a saved prototype’s relaunch.
Precedence (#12522). The rules below are implemented once as the pure function
restorePrototypeStorage (src/features/prototype/prototypeStorageRestore.ts), the reference the device
runtimes follow, as applyPrototypeDataWrite is for data actions.
- On the next show of the same
id, stored values replace the spec’s values for the keys the spec lists. This applies to a same-id replacement, to a show after a dismiss and to a saved prototype’s launch. The rest of the spec’sstatestays authoritative (see Re-showing).reset: trueonly restarts pager pages and display; it does not clear storage (useclearStoragefirst). - If
storage.versiondiffers from the version the values were stored under, every stored value of that id is discarded and the spec’s values stand. Authors bumpversionwhen a key’s meaning or shape changes. - A stored key that
storage.keysno longer lists is dropped, and a show with nostorageblock drops every stored value of that id (as ifkeyswere empty). - A stored value that no longer fits the spec is dropped, the spec’s value stands, and the device deletes the dropped entry from storage. Such values are:
- a
statevalue whose type (string, finite number, boolean) differs from the spec’s value; - a
statekey the spec no longer declares; - a
datavalue of a different JSON kind than the spec’s own value at that pointer (object, array, string, number, boolean); - a value
applyPrototypeDataWriterefuses as aset(a missing parent, a data limit). - Restoring happens before the first draw and sends no
changeevent; the show result and the host’s cached state and data still describe the spec’s values. Callinspectto read the live values. - Host
patchagainst a stored key. The patch wins. It applies under the existingbaseRevisionconflict rules. A stored restore is not a device write, so it does not bump the revision or enter the write log. The device then stores the new value like any other write.
Host tool support.
inspectreports what the device stores. The device reports, per prototype in itsinspect_prototypesreply (and flat in the iOS agent’s status), astorageobject:{version, keys: [{key, bytes}], totalBytes, skippedKeys?}(PrototypeStorageReport). Itskeysfield lists only keys that currently hold a stored value, in storage-key form (state:darkMode,data:/cart). The host passes it through asstorageon the prototype entry. It reports it absent when the device sends none (noprototype_storage_v1, or nostorageblock) or sends a malformed one. Thestatusaction shows the last inspected value and drops it after a successfulclearStorage.{action: "clearStorage", id}wipes the stored values ofid. The host sends{type: "clear_prototype_storage", requestId, id}(Android CtrlProxy; the iOS agent receives the same request type). The device answers oneprototype_resultwithsuccessandcleared, the number of keys removed (0 for an id with nothing stored). The action leaves the prototype on screen unchanged; the next show of the id starts from the spec’s values. When the device does not advertiseprototype_storage_v1, the host refuses the action before sending anything, with a message naming that capability.deleteSavedalso clears the id’s storage. This is device-side behavior and part of the contract: deleting a saved prototype removes its spec, assets, shortcut and stored values, so a later save of the same id starts clean. Thedelete_saved_prototyperequest needs no new flag. On iOS the saved prototype is its own app, so deleting the app removes its storage with it.
Android CtrlProxy (#12525). Advertises prototype_storage_v1; the rules live in
PrototypeStorageRestorer (android/protocol, the pure twin of restorePrototypeStorage),
PrototypeStoragePersistence / PrototypeStorageSession and PrototypeStorageStore
(android/control-proxy/.../prototype).
- Store.
PrototypeStorageDirectoryStorekeeps one document per id atfilesDir/prototype-storage/<slug>-<hash16>.json(slug as saved prototypes use, then 16 hex chars of the id’s SHA-256):{"id", "version", "values": {"state:dark": true, "data:/cart": {...}}}. A save writes<name>.tmp, syncs and renames, so a reader sees the old or new document. An unparsable document, wrong shape or another id’s document isCorrupt: the show uses the spec’s values, logs a warning and deletes it. - Show. Restore runs before the device builds the runtime, so the first draw has the stored values;
the runtime starts at the spec’s revision and sends no
change. The device deletes dropped entries at once. The restored spec must pass the same validation as a shown one (a stored text breakingmaxLengthwould not), otherwise the device drops every stored value. A same-id show first flushes the shown prototype’s pending write. - Write-back. After each interaction and patch the session compares the listed keys with what it last
saw and stores only those that changed, so an untouched key keeps following the spec. The first change of
a burst arms one write
PROTOTYPE_STORAGE_DEBOUNCE_MILLIS(500 ms) later; dismissal (any reason, including teardown), replacement and the saved activity’sonStopflush at once. A failed write is logged and retried at the next flush.requestresponses are covered because they write through the same paths. - Limit. Per id, the store sums entries against
MAX_PROTOTYPE_STORAGE_BYTES. A write that would pass it applies live, but the store skips it: the key keeps its previous stored value and stays inskippedKeysuntil a later write fits. - Removed pointers. A listed
data:pointer removed by a data action loses its stored value (JSONnullis not stored), so the spec’s value returns on the next show. - Surfaces. The overlay (
PrototypeController),persistence: "device"prototypes andSavedPrototypeActivityall use it; a service prototype and the saved activity of the same id share one file (last write wins). - Host actions.
clear_prototype_storageclears the shown session (and its pending write) or, for an id nobody shows, the document. The prototype on screen keeps its live values. Thedelete_saved_prototyperequest clears the id’s storage after deleting the saved copy. - Reinstall. Stored values live in
filesDir: they survive dismiss, process restart and a saved prototype’s launch, not an uninstall, data clear or the reinstall fallback. The #12268 host mirror records saved prototypes from what the host sent atsaveand does not restore stored values.