@rocapine/rocalytics-sdk 0.0.0-stage → 0.2.0

package/dist/onboarding/tracker.js

@@ -0,0 +1,734 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onboardingRun = void 0;
+exports.createOnboardingRunTracker = createOnboardingRunTracker;
+const context_1 = require("../core/context");
+const delivery_1 = require("../core/delivery");
+const diagnostics_1 = require("../core/diagnostics");
+const ids_1 = require("../core/ids");
+const storage_1 = require("../core/storage");
+const time_1 = require("../core/time");
+const version_1 = require("../version");
+const input_1 = require("./input");
+const persisted_1 = require("./persisted");
+const state_1 = require("./state");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const NOTE_MESSAGES = {
+    truncated: "the run reached a recording limit (500 entries or 261,120 bytes): recording has stopped",
+    "too-many-answers": "an entry holds at most 50 answers: the extra answer was dropped",
+};
+function inertRun(runId) {
+    return {
+        runId,
+        currentStepKey: null,
+        enterStep() { },
+        exitStep() { },
+        setProperties() { },
+        complete() { },
+        background() { },
+    };
+}
+// Per storage key, process-wide, so they hold whichever storage object a host
+// passes (a fresh adapter on every configure() included):
+// - the last disposed tracker's writes: `drain`, bounded by its idle(), which a
+//   new tracker's first read waits for, so it sees what the old one staged;
+//   `landed`, unbounded; and each queued write, its predecessors' still to land
+//   included, so a new tracker that read before one landed writes its own
+//   state again;
+// - what the last disposed tracker hands over, with storage or without, taken
+//   by the next tracker. Known at dispose(), and newer than any write still to
+//   land: its run, when it started or resumed one (null once that run is
+//   completed or replaced), or else the run it was handed; and its unsent
+//   snapshots, which the next tracker holds (and writes) from the start. Then,
+//   once its last attempts are over, what is still unsent and what was settled.
+//   A tracker disposed without a run passes on what it was handed;
+// - how many live trackers use the key: two at once overwrite each other.
+const lastDrainOnKey = new Map();
+//   Only a tracker whose sink has the same destination takes it: one that
+//   sends elsewhere takes nothing, and discards the stored state it reads;
+const handoffOnKey = new Map();
+const liveOnKey = new Map();
+function createOnboardingRunTracker(config) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const clock = (_a = config.clock) !== null && _a !== void 0 ? _a : time_1.systemClock;
+    const timers = (_b = config.timers) !== null && _b !== void 0 ? _b : time_1.systemTimers;
+    const report = (0, diagnostics_1.safeDiagnostics)(config.onDiagnostic);
+    const fallbackUuid = (0, ids_1.createUuid)(clock);
+    const debounceMs = (_c = config.debounceMs) !== null && _c !== void 0 ? _c : 500;
+    // Set only when the stored value was READ and found unparseable or malformed,
+    // so it is rewritten without the bad part. A failed read never sets it.
+    let rewrite = false;
+    // Set when the stored value must not be touched: storage could not be read
+    // (twice), or it holds a format this version does not know. The session then
+    // runs without persistence, and the stored value is left as it is.
+    let persistenceOff = false;
+    // The slow read was reported (once).
+    let readSlow = false;
+    const storageKey = (_d = config.storageKey) !== null && _d !== void 0 ? _d : "rocalytics-sdk:onboarding-run";
+    const store = config.storage
+        ? (0, storage_1.createSerialStore)(config.storage, storageKey, (e) => report({ code: "storage", message: `storage failed: ${String(e)}` }))
+        : null;
+    if (store) {
+        const others = (_e = liveOnKey.get(storageKey)) !== null && _e !== void 0 ? _e : 0;
+        if (others > 0) {
+            report({
+                code: "storage",
+                message: `another live tracker already uses storageKey "${storageKey}": trackers running at once must each use their own storageKey, or they overwrite each other's unsent snapshots`,
+            });
+        }
+        liveOnKey.set(storageKey, others + 1);
+    }
+    const deliveries = new Map();
+    const outboxes = new Map();
+    // Per run, the highest seq a sink settled, here or in the predecessor.
+    const settledSeqs = new Map();
+    // Sends waiting for their snapshot's write (at most persistTimeoutMs).
+    const staging = new Set();
+    // Writes queued and not yet done.
+    const writing = new Set();
+    // Where this tracker's snapshots go; stamped on what it stores.
+    const destination = typeof ((_f = config.sink) === null || _f === void 0 ? void 0 : _f.destination) === "string" ? config.sink.destination : undefined;
+    // Taken once: a later tracker on this key gets this one's handoff, not the predecessor's.
+    const offered = handoffOnKey.get(storageKey);
+    handoffOnKey.delete(storageKey);
+    // A predecessor that sent elsewhere: nothing it left is taken, in memory or from storage.
+    const destinationChanged = !!offered &&
+        (offered.destination !== undefined && destination !== undefined ? offered.destination !== destination : offered.sink !== config.sink);
+    // Reported once, and only when something is discarded: a switch that leaves nothing is not a loss.
+    let discardReported = false;
+    const reportDiscarded = (message) => {
+        if (discardReported)
+            return;
+        discardReported = true;
+        report({ code: "destination-changed", message });
+    };
+    const replacedElsewhere = `the tracker this one replaces on storageKey "${storageKey}" sent to another destination: what it left is discarded, not sent here`;
+    if (offered && destinationChanged) {
+        if ((_g = offered.run) === null || _g === void 0 ? void 0 : _g.current)
+            reportDiscarded(replacedElsewhere); // a run in progress
+        // Its unsent snapshots are known once its last attempts are answered: those delivered are not lost.
+        void offered.left.then((left) => left.unsent.size > 0 && reportDiscarded(replacedElsewhere)).catch(() => undefined);
+    }
+    const handed = destinationChanged ? undefined : offered;
+    const predecessor = handed === null || handed === void 0 ? void 0 : handed.left;
+    // The predecessor's run: when set, it replaces the stored one, which a late write may not have updated.
+    const handedRun = handed === null || handed === void 0 ? void 0 : handed.run;
+    const priorWrites = store ? lastDrainOnKey.get(storageKey) : undefined;
+    // The predecessor's unsent snapshots, and stored outboxes read before its last
+    // attempts were over: kept (so every write holds them), and sent after them.
+    const heldBack = new Map(handed === null || handed === void 0 ? void 0 : handed.outboxes);
+    for (const [runId, item] of heldBack)
+        outboxes.set(runId, item);
+    let inheritedDone = !predecessor;
+    let live = null;
+    // A run was started (or resumed) this session: the previous launch's run is then abandoned,
+    // whether or not the run started here is still live.
+    let startedThisSession = false;
+    let persistedCurrent = (_h = handedRun === null || handedRun === void 0 ? void 0 : handedRun.current) !== null && _h !== void 0 ? _h : null;
+    let disposed = false;
+    const mintRunId = () => {
+        try {
+            const id = config.uuid ? String(config.uuid()).toLowerCase() : fallbackUuid();
+            if (UUID.test(id))
+                return id;
+            report({ code: "invalid-uuid", message: `the uuid option returned "${id}", not a UUID: using the default` });
+        }
+        catch (e) {
+            report({ code: "invalid-uuid", message: `the uuid option threw: ${String(e)}` });
+        }
+        return fallbackUuid();
+    };
+    const delivered = (runId, item) => { var _a; return item.seq <= ((_a = settledSeqs.get(runId)) !== null && _a !== void 0 ? _a : 0); };
+    const compose = () => {
+        const current = live && live.state.status === "in_progress" ? live.state : persistedCurrent;
+        if (!current && outboxes.size === 0)
+            return null;
+        return { format: 1, ...(destination === undefined ? {} : { destination }), current, outboxes: Object.fromEntries(outboxes) };
+    };
+    // Persisted outboxes are merged in before anything is written, so a write
+    // composed this session never drops a snapshot left by the previous one.
+    // Every stored part is validated first; an invalid one is dropped, reported,
+    // and the stored value rewritten without it. This promise never rejects.
+    const loaded = store
+        ? store
+            .read(priorWrites === null || priorWrites === void 0 ? void 0 : priorWrites.drain) // after a disposed predecessor's last writes
+            .then((result) => {
+            var _a, _b;
+            if (result.status === "failed") {
+                persistenceOff = true;
+                return report({
+                    code: "storage",
+                    message: `reading stored state failed twice (${String(result.error)}): it is left untouched, and this session runs without persistence`,
+                });
+            }
+            if (result.status === "invalid") {
+                rewrite = true;
+                return report({ code: "storage", message: "the stored state is not JSON: discarded" });
+            }
+            const raw = result.value;
+            if (raw === null)
+                return;
+            const format = raw.format;
+            if (raw && typeof raw === "object" && !Array.isArray(raw) && typeof format === "number" && format !== 1) {
+                persistenceOff = true;
+                return report({
+                    code: "storage",
+                    message: `the stored state has format ${format}, which this version does not know: it is left untouched, and this session runs without persistence`,
+                });
+            }
+            const { current, outboxes: stored, problems } = (0, persisted_1.parsePersisted)(raw);
+            if (problems.length) {
+                rewrite = true;
+                report({ code: "storage", message: `${problems.join("; ")}: discarded` });
+            }
+            // What is left, written for another destination: never sent here, so discarded.
+            if (destinationChanged || raw.destination !== destination) {
+                if (!current && stored.length === 0)
+                    return;
+                rewrite = true;
+                return reportDiscarded(destinationChanged
+                    ? replacedElsewhere
+                    : "the stored state was written for another destination than this sink's: discarded, nothing of it is sent");
+            }
+            // Merged even after dispose(), so a write still queued keeps them; but
+            // sent only before it, and only once the predecessor's last attempts
+            // are over (the snapshots they deliver are dropped, not sent again).
+            for (const [runId, item] of stored) {
+                if (((_b = (_a = outboxes.get(runId)) === null || _a === void 0 ? void 0 : _a.seq) !== null && _b !== void 0 ? _b : 0) >= item.seq)
+                    continue;
+                if (delivered(runId, item))
+                    rewrite = true;
+                else if (!inheritedDone) {
+                    outboxes.set(runId, item);
+                    heldBack.set(runId, item);
+                }
+                else if (disposed)
+                    outboxes.set(runId, item);
+                else
+                    deliveryFor(runId).enqueue(item);
+            }
+            if (current && current.status === "in_progress" && !handedRun) {
+                if (!startedThisSession)
+                    persistedCurrent = current;
+                else
+                    sendAbandoned(current); // a new run started before storage was read
+            }
+        })
+            .catch((e) => report({ code: "storage", message: `loading stored state failed: ${String(e)}` }))
+            .then(() => {
+            if (rewrite && !persistenceOff && !disposed)
+                void persist();
+            rewrite = false;
+        })
+        : Promise.resolve();
+    /**
+     * The predecessor's handoff, once its last attempts are over: what it left
+     * unsent is kept and sent from here, with the stored outboxes held back for
+     * it. Per run, only a snapshot newer than the one held here and than any the
+     * predecessor's sink settled. Never rejects.
+     */
+    const inherited = predecessor
+        ? predecessor
+            .then((handoff) => {
+            var _a;
+            for (const [runId, seq] of handoff.settled)
+                settledSeqs.set(runId, Math.max(seq, (_a = settledSeqs.get(runId)) !== null && _a !== void 0 ? _a : 0));
+            let dropped = false;
+            for (const [runId, item] of [...heldBack, ...handoff.unsent]) {
+                const held = outboxes.get(runId);
+                if (delivered(runId, item)) {
+                    if (held === item) {
+                        outboxes.delete(runId);
+                        dropped = true;
+                    }
+                }
+                else if (!held || held === item || held.seq < item.seq) {
+                    if (disposed)
+                        outboxes.set(runId, item); // passed on to the next tracker
+                    else
+                        deliveryFor(runId).enqueue(item); // persisted by onPendingChange
+                }
+            }
+            heldBack.clear();
+            if (dropped)
+                persist();
+        })
+            .catch((e) => report({ code: "internal-error", message: `adopting a disposed tracker's snapshots: ${String(e)}` }))
+            .then(() => {
+            inheritedDone = true;
+        })
+        : Promise.resolve();
+    // Each predecessor write that lands after this tracker read storage replaces
+    // what it wrote: this tracker writes its state again once it holds a state
+    // at least as new, that is once it has a run of its own or was handed the
+    // predecessor's. (Otherwise start() or resume() writes it anyway.)
+    if (priorWrites) {
+        let drained = false;
+        void priorWrites.drain.then(() => (drained = true));
+        for (const write of priorWrites.writes) {
+            void write.then(() => {
+                if (drained && (startedThisSession || handedRun || destinationChanged))
+                    persist();
+            });
+        }
+    }
+    /**
+     * A run left in progress by the previous launch and not resumed: if it holds
+     * a change that never went into a send (killed inside the debounce window),
+     * send it now, so the latest snapshot is not lost (section 5).
+     */
+    function sendAbandoned(state) {
+        if (!state.dirty || state.steps.length === 0)
+            return;
+        const seq = state.lastSeq + 1;
+        stageAndSend(state.runId, { seq, body: (0, state_1.toSnapshot)(state, seq, Math.max(clock.now(), (0, state_1.floorMs)(state))) }, false);
+    }
+    const persistTimeoutMs = (_j = config.persistTimeoutMs) !== null && _j !== void 0 ? _j : 1000;
+    const storageReadTimeoutMs = (_k = config.storageReadTimeoutMs) !== null && _k !== void 0 ? _k : 5000;
+    /** `p`, or `false` once `ms` have passed without it settling. Never rejects. */
+    const within = (p, ms) => new Promise((resolve) => {
+        const timer = timers.setTimeout(() => resolve(false), ms);
+        p.then((v) => {
+            timers.clearTimeout(timer);
+            resolve(v);
+        }, () => {
+            timers.clearTimeout(timer);
+            resolve(false);
+        });
+    });
+    /**
+     * Waits for the stored state to be read, at most storageReadTimeoutMs, and
+     * reports a read that takes longer. The read itself goes on: resume() still
+     * waits for it, and writes, each queued behind it and composed after it, go
+     * on with what it found once it lands.
+     */
+    const waitLoaded = async () => {
+        if (!store)
+            return true;
+        const ok = await within(loaded.then(() => true), storageReadTimeoutMs);
+        if (!ok && !readSlow) {
+            readSlow = true;
+            report({
+                code: "storage",
+                message: `the stored state has not been read within ${storageReadTimeoutMs} ms: resume() waits for it`,
+            });
+        }
+        return ok;
+    };
+    /**
+     * Queues a write of the whole tracker state, in order, right away; its value
+     * is composed when its turn comes (after the stored state was read). A write
+     * queued before dispose() still happens: that is how dispose() keeps a
+     * staged snapshot. Never rejects; resolves once the write is done or failed.
+     */
+    const persist = () => {
+        if (!store || disposed)
+            return Promise.resolve();
+        const write = store.saveWith(async () => {
+            await loaded;
+            return persistenceOff ? undefined : compose();
+        });
+        writing.add(write);
+        void write.then(() => writing.delete(write));
+        return write;
+    };
+    /**
+     * Stores a snapshot as the run's unsent one, together with the state that
+     * assigned its seq, and only then hands it to the sink (3.2: persist on
+     * every change). Waits at most `persistTimeoutMs` for the write.
+     */
+    function stageAndSend(runId, item, flush) {
+        outboxes.set(runId, item);
+        // Not gated on dispose(): a snapshot staged before it is still sent (once; see deliveryFor).
+        const send = () => {
+            const d = deliveryFor(runId);
+            d.enqueue(item);
+            if (flush)
+                d.flush();
+        };
+        if (!store)
+            return send();
+        let done = false;
+        let sent = () => { };
+        const staged = new Promise((resolve) => (sent = resolve));
+        staging.add(staged);
+        const once = () => {
+            if (done)
+                return;
+            done = true;
+            timers.clearTimeout(timer);
+            staging.delete(staged);
+            send();
+            sent();
+        };
+        const timer = timers.setTimeout(once, persistTimeoutMs);
+        void persist().then(once);
+    }
+    function deliveryFor(runId) {
+        let d = deliveries.get(runId);
+        if (!d) {
+            d = (0, delivery_1.createDelivery)({
+                sink: config.sink,
+                timers,
+                retry: config.retry,
+                attemptTimeoutMs: config.attemptTimeoutMs,
+                onPendingChange: (pending) => {
+                    var _a, _b;
+                    // Only ever moves forward: a newer snapshot may already be staged for this run.
+                    if (pending && ((_b = (_a = outboxes.get(runId)) === null || _a === void 0 ? void 0 : _a.seq) !== null && _b !== void 0 ? _b : 0) <= pending.seq) {
+                        outboxes.set(runId, pending);
+                        persist();
+                    }
+                },
+                onSettled: (item, result) => {
+                    var _a;
+                    settledSeqs.set(runId, Math.max(item.seq, (_a = settledSeqs.get(runId)) !== null && _a !== void 0 ? _a : 0));
+                    const staged = outboxes.get(runId);
+                    if (staged && staged.seq <= item.seq) {
+                        outboxes.delete(runId);
+                        persist();
+                    }
+                    if (result.outcome === "rejected") {
+                        report({
+                            code: "rejected",
+                            runId,
+                            message: `snapshot seq ${item.seq} was rejected by the ingest${result.reason ? `: ${result.reason}` : ""}`,
+                        });
+                    }
+                },
+            });
+            deliveries.set(runId, d);
+            if (disposed)
+                d.close(); // after dispose(): one last attempt per snapshot, no retry timers
+        }
+        return d;
+    }
+    /** Resolves once queued storage writes are done, however long they take. */
+    const writesDone = async () => {
+        if (!store)
+            return;
+        for (let i = 0; i < 3; i++) {
+            await store.idle();
+            await Promise.resolve();
+        }
+    };
+    /** Waits up to storageReadTimeoutMs for the read, then as long again for `writes`. */
+    const idleWithin = async (writes) => {
+        if (!store || !(await waitLoaded()))
+            return;
+        await within(writes, storageReadTimeoutMs);
+    };
+    /**
+     * What this disposed tracker leaves unsent, once its last attempts are
+     * over: the predecessor's handoff taken in, every send that waited for its
+     * write handed to the sink, and no attempt in flight. Each attempt is bounded
+     * by attemptTimeoutMs, and each wait for a write by persistTimeoutMs.
+     */
+    const leftUnsent = async () => {
+        await inherited;
+        do {
+            await Promise.all(staging);
+            await Promise.all([...deliveries.values()].map((d) => d.idle()));
+        } while (staging.size > 0);
+        return { unsent: new Map(outboxes), settled: new Map(settledSeqs) };
+    };
+    class Controller {
+        constructor(state) {
+            this.active = true;
+            this.debounce = null;
+            this.state = state;
+        }
+        get runId() {
+            return this.state.runId;
+        }
+        get currentStepKey() {
+            var _a, _b;
+            return (_b = (_a = this.state.steps[this.state.steps.length - 1]) === null || _a === void 0 ? void 0 : _a.step_key) !== null && _b !== void 0 ? _b : null;
+        }
+        now() {
+            return Math.max(clock.now(), (0, state_1.floorMs)(this.state));
+        }
+        diag(code, message) {
+            report({ code, message, runId: this.state.runId });
+        }
+        /** Runs a public method body: never throws, and refuses once the run is over. */
+        guard(name, body, allowCompleted = false) {
+            try {
+                if (disposed)
+                    return;
+                if (!this.active)
+                    return this.diag("run-inactive", `${name}: a newer run was started; this one records nothing more`);
+                if (this.state.status === "completed" && !allowCompleted) {
+                    return this.diag("run-completed", `${name}: the run is completed and records nothing more`);
+                }
+                body();
+            }
+            catch (e) {
+                this.diag("internal-error", `${name}: ${String(e)}`);
+            }
+        }
+        apply(result, send) {
+            for (const note of result.notes)
+                this.diag(note, NOTE_MESSAGES[note]);
+            this.state = result.changed ? { ...result.state, dirty: true } : result.state;
+            persist();
+            if (!result.changed)
+                return;
+            if (send === "now" || debounceMs <= 0)
+                this.sendNow();
+            else if (this.debounce === null)
+                this.debounce = timers.setTimeout(() => this.sendNow(), debounceMs);
+        }
+        /** Sends the run now. `flush` also skips a backoff in progress (completion, background). */
+        sendNow(flush = false) {
+            if (this.debounce !== null)
+                timers.clearTimeout(this.debounce);
+            this.debounce = null;
+            if (disposed || this.state.steps.length === 0)
+                return;
+            const now = this.now();
+            const seq = this.state.lastSeq + 1;
+            const body = (0, state_1.toSnapshot)(this.state, seq, now);
+            this.state = {
+                ...this.state,
+                lastSeq: seq,
+                lastActiveAt: this.state.status === "in_progress" ? now : this.state.lastActiveAt,
+                dirty: false,
+            };
+            stageAndSend(this.state.runId, { seq, body }, flush);
+        }
+        /** A change waiting on the debounce is sent now. */
+        flushDebounce() {
+            if (this.debounce !== null)
+                this.sendNow();
+        }
+        deactivate() {
+            this.flushDebounce(); // a change waiting on the debounce still goes out
+            this.active = false;
+        }
+        enterStep(stepKey) {
+            this.guard("enterStep", () => {
+                if (typeof stepKey !== "string" || !this.state.manifest.steps.some((s) => s.step_key === stepKey)) {
+                    return this.diag("unknown-step", `enterStep: "${String(stepKey)}" is not in the manifest`);
+                }
+                const last = this.state.steps[this.state.steps.length - 1];
+                if (last && last.step_key === stepKey && last.exited_at === null) {
+                    return this.diag("already-on-step", `enterStep: already on "${stepKey}"`);
+                }
+                this.apply((0, state_1.enter)(this.state, stepKey, this.now()), "debounced");
+            });
+        }
+        exitStep(stepKey, options) {
+            this.guard("exitStep", () => {
+                var _a, _b;
+                const steps = this.state.steps;
+                let index = -1;
+                if (((_a = steps[steps.length - 1]) === null || _a === void 0 ? void 0 : _a.step_key) === stepKey)
+                    index = steps.length - 1;
+                else if (((_b = steps[steps.length - 2]) === null || _b === void 0 ? void 0 : _b.step_key) === stepKey)
+                    index = steps.length - 2;
+                if (index < 0)
+                    return this.diag("not-current-step", `exitStep: "${String(stepKey)}" is not the current step`);
+                const raw = options && Array.isArray(options.answers) ? options.answers : [];
+                if ((options === null || options === void 0 ? void 0 : options.answers) !== undefined && !Array.isArray(options.answers)) {
+                    this.diag("invalid-answer", "exitStep: answers must be an array");
+                }
+                const answers = [];
+                for (const input of raw) {
+                    const r = (0, input_1.toAnswer)(input);
+                    if (r.ok)
+                        answers.push(r.answer);
+                    else
+                        this.diag("invalid-answer", r.error);
+                }
+                this.apply((0, state_1.exit)(this.state, index, answers, this.now()), "debounced");
+            });
+        }
+        setProperties(properties) {
+            this.guard("setProperties", () => {
+                var _a;
+                const { value, problems } = (0, input_1.mergeProperties)((_a = this.state.properties) !== null && _a !== void 0 ? _a : {}, properties);
+                for (const [code, message] of problems)
+                    this.diag(code, message);
+                this.apply((0, state_1.setProperties)(this.state, value, this.now()), "debounced");
+            });
+        }
+        complete() {
+            this.guard("complete", () => {
+                if (this.state.steps.length === 0)
+                    return this.diag("no-steps", "complete: no step was entered, so there is no run to send");
+                this.state = (0, state_1.completeState)(this.state, this.now());
+                if (live === this)
+                    live = null;
+                this.sendNow(true);
+            });
+        }
+        background() {
+            this.guard("background", () => {
+                if (this.state.status === "completed")
+                    return deliveryFor(this.state.runId).flush();
+                if (this.state.steps.length === 0)
+                    return this.diag("no-steps", "background: no step was entered yet");
+                this.state = { ...this.state, lastActiveAt: this.now() };
+                this.sendNow(true);
+            }, true);
+        }
+    }
+    return {
+        start(options) {
+            try {
+                if (disposed)
+                    return inertRun(mintRunId());
+                let contextInput;
+                try {
+                    contextInput = typeof config.context === "function" ? config.context() : config.context;
+                }
+                catch (e) {
+                    report({ code: "invalid-start", message: `the context function threw: ${String(e)}` });
+                    return inertRun(mintRunId());
+                }
+                const context = (0, context_1.captureRunContext)(contextInput, version_1.LIBRARY_VERSION);
+                const valid = (0, input_1.validateStart)(options);
+                const errors = [...(context.ok ? [] : context.errors), ...(valid.ok ? [] : valid.errors)];
+                if (!context.ok || !valid.ok) {
+                    report({ code: "invalid-start", message: `run not started, nothing will be sent: ${errors.join("; ")}` });
+                    return inertRun(mintRunId());
+                }
+                for (const [code, message] of valid.value.warnings)
+                    report({ code, message });
+                if (live && live.state.status === "in_progress") {
+                    report({ code: "run-replaced", runId: live.runId, message: "a new run was started; the previous one stays in progress" });
+                    live.deactivate();
+                }
+                if (persistedCurrent)
+                    sendAbandoned(persistedCurrent);
+                persistedCurrent = null;
+                const { onboarding, studio, manifest, properties } = valid.value;
+                const state = {
+                    runId: mintRunId(),
+                    lastSeq: 0,
+                    onboarding,
+                    ...(studio ? { studio } : {}),
+                    context: context.context,
+                    manifest,
+                    ...(properties ? { properties } : {}),
+                    steps: [],
+                    provisionalExit: false,
+                    truncated: false,
+                    status: "in_progress",
+                    completedAt: null,
+                    lastActiveAt: clock.now(),
+                };
+                live = new Controller(state);
+                startedThisSession = true;
+                persist();
+                return live;
+            }
+            catch (e) {
+                report({ code: "internal-error", message: `start: ${String(e)}` });
+                return inertRun(fallbackUuid());
+            }
+        },
+        async resume() {
+            try {
+                void waitLoaded(); // reports a slow read
+                await loaded;
+                if (disposed || startedThisSession || !persistedCurrent)
+                    return null;
+                const state = persistedCurrent;
+                persistedCurrent = null;
+                const now = Math.max(clock.now(), (0, state_1.floorMs)(state), state.lastActiveAt);
+                const controller = new Controller(state);
+                live = controller;
+                startedThisSession = true;
+                const result = (0, state_1.restore)(state, now);
+                for (const note of result.notes)
+                    report({ code: note, runId: state.runId, message: NOTE_MESSAGES[note] });
+                controller.state = result.state;
+                persist();
+                controller.sendNow();
+                return controller;
+            }
+            catch (e) {
+                report({ code: "internal-error", message: `resume: ${String(e)}` });
+                return null;
+            }
+        },
+        // Waits up to storageReadTimeoutMs for the read, then as long again for queued writes.
+        async idle() {
+            try {
+                await idleWithin(writesDone());
+            }
+            catch {
+                // idle() never rejects into the host
+            }
+        },
+        dispose() {
+            var _a, _b;
+            if (disposed)
+                return;
+            // A change still waiting on the debounce becomes a staged snapshot first.
+            try {
+                live === null || live === void 0 ? void 0 : live.flushDebounce();
+            }
+            catch (e) {
+                report({ code: "internal-error", message: `dispose: ${String(e)}` });
+            }
+            // From here nothing records, nothing new starts, and no write is queued.
+            // What was staged before still goes through: its write is already queued,
+            // and its send is handed to a closed delivery (one last attempt, no retry
+            // timers). A snapshot the sink does not take is handed to the next
+            // tracker on this key, and stays in storage for the next launch.
+            disposed = true;
+            for (const d of deliveries.values())
+                d.close();
+            handoffOnKey.set(storageKey, {
+                sink: config.sink,
+                destination,
+                run: startedThisSession ? { current: live && live.state.status === "in_progress" ? live.state : null } : handedRun,
+                outboxes: new Map(outboxes),
+                left: leftUnsent(),
+            });
+            if (store) {
+                liveOnKey.set(storageKey, Math.max(0, ((_a = liveOnKey.get(storageKey)) !== null && _a !== void 0 ? _a : 1) - 1));
+                // The next tracker on this key reads only after these writes (bounded by idle()).
+                const landed = writesDone().catch(() => undefined);
+                const entry = { drain: idleWithin(landed).catch(() => undefined), landed, writes: [...((_b = priorWrites === null || priorWrites === void 0 ? void 0 : priorWrites.writes) !== null && _b !== void 0 ? _b : []), ...writing] };
+                lastDrainOnKey.set(storageKey, entry);
+                void Promise.all([landed, ...entry.writes]).then(() => {
+                    if (lastDrainOnKey.get(storageKey) === entry)
+                        lastDrainOnKey.delete(storageKey);
+                });
+            }
+        },
+    };
+}
+let instance = null;
+/**
+ * The app-wide tracker. Call `configure` once at startup, then `start` (or
+ * `resume`) for each run. Before `configure`, `start` returns a run that
+ * records nothing, and warns.
+ */
+exports.onboardingRun = {
+    configure(config) {
+        instance === null || instance === void 0 ? void 0 : instance.dispose();
+        instance = createOnboardingRunTracker(config);
+    },
+    start(options) {
+        if (instance)
+            return instance.start(options);
+        (0, diagnostics_1.consoleDiagnostics)({ code: "not-configured", message: "onboardingRun.start was called before onboardingRun.configure: nothing is tracked" });
+        return inertRun("00000000-0000-0000-0000-000000000000");
+    },
+    resume() {
+        return instance ? instance.resume() : Promise.resolve(null);
+    },
+    idle() {
+        return instance ? instance.idle() : Promise.resolve();
+    },
+    dispose() {
+        instance === null || instance === void 0 ? void 0 : instance.dispose();
+        instance = null;
+    },
+};
+//# sourceMappingURL=tracker.js.map