docs: describe script staleness as head-pinned, which is what the loader does

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Guilhem Lemouel
2026-09-08 16:55:39 +02:00
co-authored by Claude Opus 5
parent 639fb7f19d
commit 71ee0abde0
2 changed files with 11 additions and 8 deletions
@@ -40,12 +40,13 @@
draftSavedAt?: string | undefined
/** ISO timestamp of the latest deploy at this path. */
deployedAt?: string | undefined
/** Precise staleness inputs: the deployed version the draft was forked from,
* and the current deployed head. When both are set they drive `isStale` and
* the dedup key instead of the timestamps — exact, and stable across
* autosaves (the timestamp drifts past `deployedAt` as you keep editing).
* Flows/apps pass version ids; scripts pass hashes, which are strings.
* Absent (pre-feature drafts) ⇒ timestamp fallback. */
/** Precise staleness inputs: the deployed version the draft is pinned to, and
* the current deployed head. When both are set they drive `isStale` and the
* dedup key instead of the timestamps, which drift past `deployedAt` as you
* keep editing. Flows/apps pass version ids and pin the true fork point;
* scripts pass hashes and re-pin to the head on each load, so one edit after
* a dismissed stale prompt stops it recurring — the same self-healing the
* timestamps had. Absent (pre-feature drafts) ⇒ timestamp fallback. */
draftBaseVersion?: number | string | undefined
deployedHeadVersion?: number | string | undefined
/** Discard the draft and reload deployed (same as "Reset to deployed"). */
@@ -106,8 +106,10 @@
* (our draft is behind the latest deploy). Cleared between loads to re-fire. */
let draftSavedAt = $state<string | undefined>(undefined)
let deployedAt = $state<string | undefined>(undefined)
/** Hash the draft forked from, and the deployed head — the script equivalent
* of the flow/app version pair. */
/** The hash the draft is pinned to, and the deployed head — the script
* equivalent of the flow/app version pair. Read off the loaded draft, which
* the load below re-pins to the head, so this is the head the draft was last
* loaded against rather than the point it originally forked from. */
let draftBaseHash = $state<string | undefined>(undefined)
let deployedHeadHash = $state<string | undefined>(undefined)