mandala-computer-mcp 0.3.0 → 0.5.0

package/dist/events.js

@@ -179,6 +179,8 @@ export class Subscription {
     #nextIndex = 0;
     /** The index after the last event handed to the model. */
     #delivered = 0;
+    /** The cursor immediately before the oldest event still in the ring. */
+    #beforeOldestCursor;
     /** Set once the model has read anything at all, so a first read can say so. */
     #read = false;
     #loss;
@@ -240,6 +242,8 @@ export class Subscription {
      * changed.
      */
     #armGen = new Map();
+    /** Next subscription-wide arm identity; active paths alone retain theirs. */
+    #nextArmGen = 0;
     /** Trees that have armed at least once in this subscription. */
     #everArmed = new Set();
     /** Re-arms a file-wait response has not explained yet. */
@@ -272,29 +276,19 @@ export class Subscription {
      * Trees a connection carrying them would not open, PROVEN so.
      *
      * Proven means the experiment came back positive — see {@link #cleared}: the
-     * tree was withheld, the same stream opened without it, and there is nothing
-     * else the difference could be. A tree merely suspected is
-     * {@link #shedCandidate} and is not in here.
+     * tree failed when added to a known working set, then that same set opened
+     * without it. A tree still being tested is not in here.
      */
     #watchRefused = new Set();
     /**
-     * The tree currently withheld from the URL to find out whether it is the
-     * reason nothing will open. `undefined` when no experiment is running.
+     * A bounded search for nominations the host will not carry.
      *
-     * It stays in {@link #watches} throughout, which is what keeps a caller from
-     * being told its tree was evicted to make room for somebody else's — this is
-     * a suspicion, not a decision about what the caller asked for.
+     * The last successful set is tried first. Once that opens, each addition is
+     * added back alone. A failed addition is removed once more for confirmation,
+     * so a host outage during the probe cannot turn an innocent tree into a
+     * refusal. Nominations stay in {@link #watches} throughout the experiment.
      */
-    #shedCandidate;
-    /**
-     * Whether a watch has been ruled out as the reason connections are failing.
-     *
-     * Set when an experiment comes back negative, cleared the moment anything
-     * greets. Without it a host that is simply DOWN would shed its way through
-     * every tree in the set two failures at a time, reporting each in turn as one
-     * the host would not carry.
-     */
-    #shedRuledOut = false;
+    #watchRecovery;
     /** What the last connection that reached an opening frame was carrying. */
     #lastGood = [];
     /** Consecutive connections that never reached an opening frame while watching. */
@@ -553,11 +547,14 @@ export class Subscription {
         const unwatchable = this.#watchLost.get(path) === 'unwatchable';
         if (unwatchable)
             this.#watchLost.delete(path);
-        const retrying = this.#watchRefused.delete(path) || this.#shedCandidate === path || unwatchable;
-        if (this.#shedCandidate === path)
-            this.#shedCandidate = undefined;
+        // A fresh request supersedes an in-flight diagnosis. The next connection
+        // carries the newly requested set and, if needed, diagnoses that set from
+        // the beginning rather than applying a conclusion to a set that changed.
+        const recovering = this.#watchRecovery !== undefined;
+        if (recovering)
+            this.#watchRecovery = undefined;
+        const retrying = this.#watchRefused.delete(path) || recovering || unwatchable;
         this.#upgradeFailures = 0;
-        this.#shedRuledOut = false;
         const at = this.#watches.indexOf(path);
         if (at >= 0) {
             // Most recently asked about goes last, so the eviction below always takes
@@ -586,18 +583,10 @@ export class Subscription {
                 this.#everArmed.delete(evicted);
                 this.#undisclosedRearm.delete(evicted);
                 this.#watchRefused.delete(evicted);
-                // An experiment about a tree nobody nominates any more has nothing left
-                // to prove, and letting it finish would file a refusal against a path
-                // this stream is no longer asking for.
-                if (this.#shedCandidate === evicted)
-                    this.#shedCandidate = undefined;
-                // The arm generation is deliberately NOT deleted. It has to stay
-                // monotonic per path, because a waiter parked on this tree is holding a
-                // number from before the eviction: reset to zero and re-nominated, the
-                // tree would come back at one and that waiter would read an eviction as
-                // a re-arm — "reporting starts here, re-read the tree" about a tree that
-                // had simply been taken away from it. Eviction is told by membership,
-                // which is what `nominates` is for.
+                // Historical paths retain no metadata. Generation identities come from
+                // a subscription-wide counter, so deleting this entry still cannot let
+                // an older waiter confuse a later re-nomination with its original arm.
+                this.#armGen.delete(evicted);
             }
         }
         this.#reopen();
@@ -659,7 +648,12 @@ export class Subscription {
         this.touch();
         const attached = !this.#read;
         this.#read = true;
-        const from = this.resolveFrom(opts.since);
+        // The one place a gap the `since` cursor implies is turned into a standing
+        // loss, because this is the call that hands it to the model. Establishing it
+        // in the placement itself would stamp it on the subscription from every
+        // preview — and a preview whose caller then cancels, or a concurrent read on
+        // the same subscription, would take the gap away with it.
+        const { from, loss: standing } = this.#place(opts.since);
         const end = opts.through !== undefined ? opts.through + 1 : this.#nextIndex;
         const window = this.#ring.filter((b) => b.index >= from && b.index < end);
         // The OLDEST `limit`, not the newest, and the position advances only over
@@ -690,12 +684,12 @@ export class Subscription {
                 // An unknown count plus a known one is still unknown. Adding the two
                 // would report a precise number for a hole nobody can measure, which
                 // is the one thing a loss report must not do.
-                events: this.#loss?.events === null ? null : (this.#loss?.events ?? 0) + omitted,
-                reason: this.#loss
-                    ? `${this.#loss.reason}; and ${omitted} more than limit allowed were stepped over to reach the event you waited for`
+                events: standing?.events === null ? null : (standing?.events ?? 0) + omitted,
+                reason: standing
+                    ? `${standing.reason}; and ${omitted} more than limit allowed were stepped over to reach the event you waited for`
                     : `${omitted} events older than the one you waited for did not fit in limit and were stepped over`,
             }
-            : this.#loss;
+            : standing;
         this.#loss = undefined;
         return {
             events: batch.map((b) => b.event),
@@ -711,12 +705,17 @@ export class Subscription {
      *
      * Asked before {@link read}, because reconciliation awaits network reads and
      * a caller can cancel during them. Consuming first would advance the shared
-     * cursor and clear the loss into a response that caller never receives. This
-     * preview may establish a loss for an unknown `since`, but consumes nothing.
+     * cursor and clear the loss into a response that caller never receives.
+     *
+     * A pure preview, and that is load-bearing rather than tidiness. It sees the
+     * gap an unplaceable `since` implies, but it does not record one: a subscription
+     * is shared by every call on its computer, so a predicate that stamped `#loss`
+     * would hand that gap to whichever call read next — the cancelled caller's hole
+     * reported against a later read that named a different cursor, or none at all.
      */
     needsReconciliation(opts) {
-        const from = this.resolveFrom(opts.since);
-        if (this.#loss)
+        const { from, loss } = this.#place(opts.since);
+        if (loss)
             return true;
         if (opts.through === undefined)
             return false;
@@ -737,42 +736,75 @@ export class Subscription {
      * server holds, and saying so is the whole of the gap discipline — never a
      * frame the model has to interpret, always a sentence and, from the tool, the
      * state it would otherwise have gone to reconcile against.
+     *
+     * Reads nothing back into the subscription: see {@link #place}, which is where
+     * the sentence that gap discipline owes the model is composed, and {@link read},
+     * which is the only caller allowed to make it standing.
      */
     resolveFrom(since) {
+        return this.#place(since).from;
+    }
+    /**
+     * Placing a `since` cursor, and the loss a read from there would report.
+     *
+     * Pure. The returned `loss` is the standing loss MERGED with whatever this
+     * cursor implies, so a caller that reports it reports one hole rather than two
+     * overlapping accounts of the same evicted prefix — and a caller that only
+     * wanted the position, or only wanted to know whether there is a hole, leaves
+     * the subscription exactly as it found it.
+     */
+    #place(since) {
         // Where the model is, which is not where the socket is: it may be four
         // turns behind, and everything between the two is exactly what it has not
         // been handed yet.
-        if (since === undefined)
-            return Math.max(this.#delivered, this.#oldest);
+        if (since === undefined) {
+            return { from: Math.max(this.#delivered, this.#oldest), loss: this.#loss };
+        }
         const at = this.#ring.findIndex((b) => b.event.cursor === since);
         if (at >= 0)
-            return this.#ring[at].index + 1;
+            return { from: this.#ring[at].index + 1, loss: this.#loss };
         // An opening cursor can outlive everything that followed it in the ring.
         // Evicting already delivered events is harmless for implicit reads, but a
         // deliberate rewind asks for those events again and must hear about the hole.
         if (since === this.#hello?.cursor) {
             const missing = Math.max(0, this.#oldest - this.#helloFrom);
-            if (missing && this.#loss?.events !== null) {
-                this.#loss = {
+            const loss = missing && this.#loss?.events !== null
+                ? {
                     // Unread overflow and this rewind describe overlapping evicted
                     // prefixes. Count their union, rather than adding the same loss twice.
                     events: Math.max(missing, this.#loss?.events ?? 0),
                     reason: 'events requested from that opening cursor were dropped from this session’s buffer',
-                };
-            }
-            return Math.max(this.#helloFrom, this.#oldest);
+                }
+                : this.#loss;
+            return { from: Math.max(this.#helloFrom, this.#oldest), loss };
         }
+        // An empty `through` read can advance the delivery position to the oldest
+        // survivor without handing over an event. Its cursor is the predecessor
+        // retained during eviction, which is no longer in the ring but is still an
+        // exact, lossless place from which to resume those survivors.
+        if (since === this.#beforeOldestCursor)
+            return { from: this.#oldest, loss: this.#loss };
         // Otherwise: the unread frontier, NOT the oldest thing still in the ring.
         // A delivered event stays in the ring until the cap evicts it, so answering
         // an unplaceable cursor with `#oldest` re-sent events the model already
         // had — while attaching a loss note that said they "were not kept", which
         // was false about exactly the events being re-sent.
-        this.#loss ??= {
-            events: null,
-            reason: 'that cursor is not a place this session can find, so whatever happened between it and ' +
-                'the events below was not kept here',
+        //
+        // `events: null` whatever else is standing, and that is the same rule
+        // {@link read} applies to its own overflow: a cursor this session cannot
+        // place may be any distance back, so a count taken from this buffer offered
+        // as the size of that hole would be a precise answer to a question nobody
+        // can measure. The standing reason is kept alongside, because an eviction
+        // here and an unplaceable cursor are two true things about one gap.
+        const unplaceable = 'that cursor is not a place this session can find, so whatever happened between it and ' +
+            'the events below was not kept here';
+        return {
+            from: Math.max(this.#delivered, this.#oldest),
+            loss: {
+                events: null,
+                reason: this.#loss ? `${this.#loss.reason}; and ${unplaceable}` : unplaceable,
+            },
         };
-        return Math.max(this.#delivered, this.#oldest);
     }
     /**
      * Wait for an event this predicate accepts, or for the deadline.
@@ -936,12 +968,16 @@ export class Subscription {
         const at = this.#ring.find((b) => b.index === this.#delivered - 1)?.event.cursor;
         if (typeof at === 'string' && at)
             return at;
+        if (this.#delivered === this.#oldest && this.#beforeOldestCursor) {
+            return this.#beforeOldestCursor;
+        }
         // Nothing in the ring to place it by: either nothing has been delivered on
         // this stream at all, or the event the position sits after has been evicted.
-        // The last cursor DELIVERED before `#resume`, for the reason
-        // {@link resumeCursor} gives — a position behind the truth is re-read, a
-        // position ahead of it is a hole nothing reports.
-        return this.#deliveredCursor ?? this.#resume ?? this.#hello?.cursor ?? '';
+        // The last cursor DELIVERED, or the frontier where this subscription
+        // started before anything has been handed over. Both follow the same rule
+        // as {@link resumeCursor}: a position behind the receive head may replay,
+        // while a position ahead of unread records silently skips them.
+        return this.#deliveredCursor ?? this.#start ?? this.#hello?.cursor ?? '';
     }
     #wakeAll() {
         for (const wake of [...this.#wake])
@@ -955,6 +991,9 @@ export class Subscription {
             this.#helloFrom = this.#nextIndex;
         if (this.#ring.length > MAX_BUFFERED) {
             const evicted = this.#ring.splice(0, this.#ring.length - MAX_BUFFERED);
+            const beforeOldest = evicted[evicted.length - 1]?.event.cursor;
+            this.#beforeOldestCursor =
+                typeof beforeOldest === 'string' && beforeOldest ? beforeOldest : undefined;
             // Only what the model had not been handed is a loss. Dropping events it
             // already read is the ring doing its job, and counting those would report
             // a hole where there is none.
@@ -1035,6 +1074,11 @@ export class Subscription {
             // tree, under an arming the caller is already waiting on.
             if (this.#renominate) {
                 this.#renominate = false;
+                // Recovery often closes a fallback or successful probe immediately
+                // after its greeting. It still proved the host reachable, so discard
+                // the failure backoff accumulated before that greeting.
+                if (reached)
+                    backoff = BACKOFF_MS;
                 continue;
             }
             // A connection that got as far as its opening frame is not a failure,
@@ -1232,12 +1276,17 @@ export class Subscription {
                 // `watching` is measured against, and what says whether a nomination
                 // made a moment ago is on this connection or on the next one.
                 //
-                // The nominations MINUS whatever is being withheld: a tree proven to be
-                // one this host will not carry, and the one currently under suspicion
-                // for it. Both stay in `#watches`, because they are still what the
-                // caller asked for and the difference belongs on the wire rather than
-                // in this client's record of the request.
-                this.#sent = this.#watches.filter((w) => !this.#watchRefused.has(w) && w !== this.#shedCandidate);
+                // Proven refusals stay off the wire. During diagnosis, the last working
+                // set is sent alone or with exactly one candidate; all nominations stay
+                // in `#watches`, because an experiment is not an eviction.
+                const recovery = this.#watchRecovery;
+                const included = recovery
+                    ? new Set([
+                        ...recovery.baseline,
+                        ...(recovery.phase === 'probe' && recovery.candidate ? [recovery.candidate] : []),
+                    ])
+                    : undefined;
+                this.#sent = this.#watches.filter((w) => !this.#watchRefused.has(w) && (!included || included.has(w)));
                 for (const w of this.#sent)
                     target.searchParams.append('watch', w);
                 socket = this.#socketFor(target.toString());
@@ -1330,6 +1379,8 @@ export class Subscription {
         const buffered = this.#ring.find((b) => b.event.cursor === hello.cursor);
         if (buffered)
             this.#helloFrom = buffered.index + 1;
+        else if (hello.cursor === this.#beforeOldestCursor)
+            this.#helloFrom = this.#oldest;
         else if (hello.cursor !== this.#hello?.cursor)
             this.#helloFrom = this.#nextIndex;
         // The same greeting on a reconnect must retain its original frontier,
@@ -1341,7 +1392,7 @@ export class Subscription {
         // could be observed from otherwise — and a connection that WORKS does not
         // end for minutes or hours. An experiment whose positive result was only
         // read on the way out is an experiment with no result.
-        this.#cleared();
+        const continueWatchRecovery = this.#cleared();
         this.#adoptWatching(hello.watching);
         this.#resume ??= hello.cursor || undefined;
         this.#start ??= hello.cursor || undefined;
@@ -1362,6 +1413,12 @@ export class Subscription {
         // that is a new session. One extra readiness is the cheaper wrong answer.
         if (hello.ready && !resuming)
             this.#pushReady(hello.cursor);
+        // Advance only after this greeting has been fully adopted. Closing in
+        // `#cleared` would let its remaining work set `open` and armed state after
+        // the socket had already finished, briefly making an intermediate probe
+        // look like the connection about to replace it.
+        if (continueWatchRecovery)
+            this.#reopen();
         this.#wakeAll();
     }
     /**
@@ -1409,6 +1466,11 @@ export class Subscription {
         }
         sent.forEach((nominated, i) => {
             const w = watching[i];
+            // Keep the original index: `watching[i]` answers `sent[i]`, even when an
+            // earlier nomination was evicted while this connection was closing.
+            // The evicted entry itself must write nothing back into active metadata.
+            if (!this.#watches.includes(nominated))
+                return;
             if (w.path !== nominated)
                 this.#hostName.set(nominated, w.path);
             armed.set(nominated, w.armed);
@@ -1453,56 +1515,112 @@ export class Subscription {
      * reconnecting forever with nothing ever saying why.
      *
      * But a host that is down fails in exactly the same way, so two missed
-     * handshakes are not proof of anything. The experiment is: drop the newest
-     * tree and try again WITHOUT it. If that connection greets, the tree was the
-     * problem and this server can say so. If it fails too, the tree was innocent
-     * — it goes back, and nothing is claimed about the host beyond its being
-     * unreachable, which the reconnect loop was already handling.
+     * handshakes are not proof of anything. Recovery first returns to the last
+     * set that opened. If that fallback opens, each new nomination is added back
+     * alone. A candidate that fails is withheld once more and blamed only when
+     * the known-good set opens again. If that set also fails, recovery keeps it
+     * as the reconnect target and retests the candidate after the host returns.
      */
     #cleared() {
-        // Whatever was withheld is now proven guilty: this is the same stream
-        // without it, and it opened.
-        if (this.#shedCandidate !== undefined) {
-            this.#watchRefused.add(this.#shedCandidate);
-            this.#shedCandidate = undefined;
+        const recovery = this.#watchRecovery;
+        if (!recovery) {
+            this.#lastGood = [...this.#sent];
+            this.#upgradeFailures = 0;
+            return false;
+        }
+        // A `fallback` that opens proves only that the host is up and that the last
+        // working set still works. It is deliberately NOT a branch here, not even
+        // for a single addition: the full set failed twice, and a host that was down
+        // for those two attempts fails exactly as a refused nomination does, so the
+        // one thing the fallback opening cannot tell us is which of the two it was.
+        // Filing the only pending tree as refused from here read an outage as a
+        // refusal — the addition fell out of the watch set, and the model was told
+        // this host would not carry a tree it would have carried. The probe below
+        // costs one round trip and answers the question instead of guessing at it.
+        if (recovery.phase === 'recover') {
+            // A fallback failed too, so the outage made the preceding evidence
+            // ambiguous. Now that the known-good set is back, test that candidate
+            // again instead of filing a refusal from before the outage.
+            recovery.candidate ??= recovery.pending.shift();
+            if (recovery.candidate !== undefined) {
+                recovery.phase = 'probe';
+                this.#lastGood = [...recovery.baseline];
+                this.#upgradeFailures = 0;
+                return true;
+            }
+        }
+        else if (recovery.phase === 'probe' && recovery.candidate !== undefined) {
+            // This candidate opened beside the known-good set, so retain it while the
+            // remaining additions are tested.
+            recovery.baseline.push(recovery.candidate);
         }
-        this.#lastGood = [...this.#sent];
+        else if (recovery.phase === 'confirm' && recovery.candidate !== undefined) {
+            // The candidate failed beside this set and the same set has now reopened
+            // without it. Only here is a refusal proven.
+            this.#watchRefused.add(recovery.candidate);
+        }
+        recovery.candidate = undefined;
+        const next = recovery.pending.shift();
+        if (next !== undefined) {
+            recovery.candidate = next;
+            recovery.phase = 'probe';
+            this.#lastGood = [...recovery.baseline];
+            this.#upgradeFailures = 0;
+            return true;
+        }
+        this.#lastGood = [...recovery.baseline];
+        this.#watchRecovery = undefined;
         this.#upgradeFailures = 0;
-        this.#shedRuledOut = false;
+        return false;
     }
     /** @see {@link #cleared} — the other half, for a connection that never greeted. */
     #blamed() {
-        if (this.#shedCandidate !== undefined) {
-            // The experiment came back negative. The tree goes back on the URL and
-            // watches stop being blamed until something connects — otherwise a host
-            // that is simply down would shed its way through every tree in the set,
-            // reporting each in turn as one the host would not carry.
-            this.#shedCandidate = undefined;
-            this.#shedRuledOut = true;
+        const recovery = this.#watchRecovery;
+        if (recovery?.phase === 'probe') {
+            // A failed probe alone is not proof: the host may have gone down after
+            // the fallback opened. Retry the known-good set before blaming the tree.
+            recovery.phase = 'confirm';
             this.#upgradeFailures = 0;
             this.#wakeAll();
             return;
         }
-        if (!this.#sent.length || this.#shedRuledOut)
+        if (recovery) {
+            // The known-good set failed too, so this is a host outage rather than
+            // evidence against a watch. Keep reconnecting that set; once it opens,
+            // the ambiguous candidate is probed again from fresh evidence.
+            recovery.phase = 'recover';
+            this.#upgradeFailures = 0;
+            this.#wakeAll();
+            return;
+        }
+        if (!this.#sent.length)
             return;
         if (++this.#upgradeFailures < WATCH_SHED_AFTER)
             return;
         this.#upgradeFailures = 0;
-        // Whatever changed since this stream last worked, and only then the newest.
-        // After an LRU refresh "newest" means "most recently asked about", which is
-        // the opposite of a good suspect: the tree a caller keeps asking about is
-        // the one least likely to be new. What the last connection that actually
-        // greeted was carrying is the real before-and-after.
         const carried = this.#sent;
-        this.#shedCandidate =
-            carried.find((w) => !this.#lastGood.includes(w)) ?? carried[carried.length - 1];
+        const baseline = this.#lastGood.filter((watch) => carried.includes(watch) && !this.#watchRefused.has(watch));
+        let pending = carried.filter((watch) => !baseline.includes(watch));
+        // If an unchanged set stops opening, retain the old single-watch experiment:
+        // remove one tree and see whether the rest still opens. This can detect a
+        // watch the host stopped accepting without reading an outage as a refusal.
+        if (!pending.length) {
+            const candidate = carried[carried.length - 1];
+            pending = [candidate];
+            baseline.splice(baseline.indexOf(candidate), 1);
+        }
+        this.#watchRecovery = { baseline, pending, phase: 'fallback' };
         this.#wakeAll();
     }
     #bumpArm(path) {
-        this.#armGen.set(path, (this.#armGen.get(path) ?? 0) + 1);
+        if (!this.#watches.includes(path))
+            return;
+        this.#armGen.set(path, ++this.#nextArmGen);
     }
     /** Record an arm, retaining later arms until a file wait explains their gap. */
     #armedTransition(path) {
+        if (!this.#watches.includes(path))
+            return;
         if (this.#everArmed.has(path))
             this.#undisclosedRearm.add(path);
         else