weir-harness 2.0.0 → 2.1.1

package/src/file-lease/plugin.js

@@ -16,6 +16,11 @@
 //     to a session that is mid-turn simply lands inside that turn and costs no
 //     extra wake. A request for a session that is not here (another process, a
 //     disposed agent) is silently dropped: the arbiter will expire it.
+//  4. Release subscriptions (D2, D4, D5): ONE in-memory coordinator per lease
+//     client, shared by every mount of this bundle. A broadcast `released` fact
+//     is consumed once and delivered as a timer-deferred full UserMessage; a
+//     connection reset is a terminal state that tells each subscriber to
+//     re-check, never that the path is free.
 //
 // The transport is process-wide (D8/D11). Two preset mounts of this bundle
 // share ONE client per socket path, and unmounting must never close it — that
@@ -28,6 +33,7 @@
 import { createLineageResolver } from './lineage.js'
 import { userTextMessage } from '../shared/user-message.js'
 import { createLeaseTools, REPLY_TOOL, shortName } from './tools.js'
+import { createWatchCoordinator } from './watch.js'
 import { AUDIT_TYPES, createAudit } from '../shared/audit.js'
 import { getSharedLeaseClient } from './singleton.js'
 import { buildLeaseView } from './view.js'
@@ -92,11 +98,87 @@ function noticedFor(agent) {
   return noticed
 }
 
+/**
+ * The settled outcomes this process has already delivered, per requesting agent.
+ *
+ * One `settled` event is one process-wide fact, but every mount hears it and the
+ * requester must be told exactly once (D4). `issued` cannot dedupe it: a turn
+ * boundary clears that map while the outcome is allowed to arrive afterwards —
+ * which is exactly when this memo is the only thing that keeps a second mount
+ * from delivering the same outcome a second time. It is keyed by the live agent
+ * because that is this process's handle on the requesting session, and it is
+ * bounded because the arbiter settles a request exactly once: forgetting an old
+ * id can only lose a repeat that never comes.
+ * @type {WeakMap<object, Map<string, number>>}
+ */
+const settledNoticesByAgent = new WeakMap()
+
+/** How many delivered outcomes one agent's memo remembers (bounded, FIFO). */
+const SETTLED_NOTICE_MEMO_LIMIT = 64
+
+/**
+ * The broker incarnation every memo entry belongs to.
+ *
+ * Request ids come from the daemon's own counter, which starts over whenever a
+ * new daemon takes the socket, so a live session can be handed an id this
+ * process already delivered an outcome for. A transport reset is the boundary
+ * between two incarnations: nothing recorded before it says anything about an id
+ * issued after it.
+ */
+let settledEpoch = 0
+
+/**
+ * Claim the one model-facing delivery of a settled outcome (D4).
+ * @param {object} agent @param {string} requestId
+ * @returns {boolean} whether this caller is the one that may deliver it
+ */
+function claimSettledNotice(agent, requestId) {
+  let notices = settledNoticesByAgent.get(agent)
+  if (notices === undefined) {
+    notices = new Map()
+    settledNoticesByAgent.set(agent, notices)
+  }
+  if (notices.get(requestId) === settledEpoch) return false
+  notices.set(requestId, settledEpoch)
+  if (notices.size > SETTLED_NOTICE_MEMO_LIMIT) {
+    // Oldest first: the ids evicted here belong to outcomes the arbiter already
+    // announced once and will never announce again.
+    const [oldest] = notices.keys()
+    if (oldest !== undefined) notices.delete(oldest)
+  }
+  return true
+}
+
 /** @param {unknown} error @returns {string} */
 function messageOf(error) {
   return String(/** @type {any} */ (error)?.message ?? error)
 }
 
+/**
+ * ONE release-subscription coordinator per lease client (design D2/D4).
+ *
+ * The client is process-wide, so its view of who waits for which path must be
+ * too: keying the coordinator by the client makes two preset mounts share one
+ * entry, one status flight and one notice, and lets either mount deliver a
+ * pending notice after the other one is gone. The map is weak because the
+ * coordinator — like the client — lives exactly as long as something holds it.
+ * @type {WeakMap<object, import('./watch.js').WatchCoordinator>}
+ */
+const watchCoordinators = new WeakMap()
+
+/**
+ * @param {object} client
+ * @returns {import('./watch.js').WatchCoordinator}
+ */
+function coordinatorFor(client) {
+  let coordinator = watchCoordinators.get(client)
+  if (coordinator === undefined) {
+    coordinator = createWatchCoordinator()
+    watchCoordinators.set(client, coordinator)
+  }
+  return coordinator
+}
+
 /**
  * The session this agent acts for: the durable header id when there is one,
  * else the live session id, else the agent id. Non-empty by construction, and
@@ -206,6 +288,39 @@ function settledText(state, requestId, short) {
   return `Request ${requestId}: no answer arrived for ${short}, so the request expired and ownership is unchanged. It becomes available when its validity ends; ask again later if you still need it.`
 }
 
+/**
+ * The release notice addressed to a subscriber (D4).
+ *
+ * It says what happened, what to do next, and — explicitly — what it does NOT
+ * mean: the arbiter selected no winner and the path may already be gone again.
+ * The path is the model's short name; an absolute path never lands in a message.
+ * @param {string} short
+ * @returns {string}
+ */
+function releasedNoticeText(short) {
+  return [
+    `${short} is no longer held by another session.`,
+    'This is only an opportunity to call edit_lock_acquire for it — not a grant of ownership, and not a reservation: another session waiting for the same release may claim it first, and the ordinary holder conflict still applies.',
+    'If your claim is refused, negotiate with edit_lock_try_steal or call edit_lock_watch again for the next release.',
+  ].join(' ')
+}
+
+/**
+ * The notice for a subscription a connection reset ended (D5).
+ *
+ * A reset says nothing about ownership, so this must not read like a release:
+ * the subscriber is told to re-check and to subscribe again if it is still
+ * refused, and nothing else.
+ * @param {string} short
+ * @returns {string}
+ */
+function resetNoticeText(short) {
+  return [
+    `The ownership arbiter connection was reset, so the release subscription for ${short} ended without learning anything about ownership.`,
+    'Nothing was released and nothing is free by this notice. Re-check with edit_lock_status, and call edit_lock_watch again if the path is still held by another session.',
+  ].join(' ')
+}
+
 /**
  * Adapt one degradation record from the lease client to the shared audit
  * channel (design D7, `AUDIT_TYPES.fileLease`).
@@ -302,10 +417,11 @@ export function createFileLeasePlugin(options = {}) {
     /** @type {Set<any>} agents whose reply tool this mount registered */
     const replyAgents = new Set()
     /**
-     * `requestId -> the session that asked for it`. A `settled` event carries no
-     * session (it is pushed to the requesting connection, which every session of
-     * this process shares), so this map is the only way to address the outcome.
-     * It is routing state, never authority: the arbiter decides (D6).
+     * `requestId -> the session that asked for it`. A `settled` event names the
+     * requester's session, but a broker older than that field pushes the outcome
+     * only to the requesting connection (which every session of this process
+     * shares), so this map remains the fallback route. It is routing state,
+     * never authority: the arbiter decides (D6).
      * @type {Map<string, { session: string, path: string }>}
      */
     const issued = new Map()
@@ -336,6 +452,28 @@ export function createFileLeasePlugin(options = {}) {
     })
     const ownerOf = injectedOwnerOf ?? createOwnerResolver(agents)
     const deliver = injectedDeliver ?? defaultDeliver
+    /**
+     * This client's release subscriptions (D2/D4). ONE coordinator per client,
+     * not per mount: two mounts that subscribe the same session and path share
+     * one entry, one status flight and one notice, and one mount's teardown
+     * cannot cancel a wait another mount still owns.
+     */
+    const watches = coordinatorFor(client)
+    /**
+     * This mount's reference on the shared coordinator plus the notice channel it
+     * speaks through. The coordinator maintains `disposed`; `notify` only renders
+     * the outcome it has already re-checked (a release fact or a reset).
+     * @type {import('./watch.js').WatchMount}
+     */
+    const watchMount = {
+      disposed: false,
+      agentFor: (/** @type {string} */ session) => agentFor(session),
+      notify: (/** @type {import('./watch.js').WatchEntry} */ entry, /** @type {any} */ agent) => {
+        const short = shortName(entry.path, cwdOf(agent))
+        notify(agent, entry.state === 'reset' ? resetNoticeText(short) : releasedNoticeText(short), agent?.status === 'idle')
+      },
+    }
+    watches.join(watchMount)
 
     /**
      * Deliver a notice without letting delivery break the caller: both channels
@@ -503,6 +641,9 @@ export function createFileLeasePlugin(options = {}) {
       const session = sessionIdOf(agent)
       retireReplyTool(agent)
       forgetIssued(session)
+      // A disposed agent never comes back: its subscriptions end with it — the
+      // active waits AND the consumed notices still waiting for their timer.
+      if (session !== undefined) watches.cancelSession(session)
       if (session === undefined) return
       quiet(() => client.releaseAll(session))
     }
@@ -553,18 +694,71 @@ export function createFileLeasePlugin(options = {}) {
       notify(agent, requestText({ requestId, short: shortName(path, cwdOf(agent)), label, fromSession, seconds }), agent?.status === 'idle')
     }
 
-    /** @param {any} event */
+    /**
+     * One negotiation outcome from the broker (D4).
+     *
+     * The event names the requester (`session`) and the path it asked about, and
+     * that pair is the routing address: a request outlives the turn that made it,
+     * while this mount's `issued` memo does not — a turn boundary clears it — so
+     * `issued` only routes an older broker's event, which names no session. An
+     * event that names neither is another process's outcome and is ignored here.
+     * @param {any} event
+     */
     function onSettled(event) {
       const requestId = text(event?.requestId)
       if (requestId === undefined) return
+      const state = text(event?.state) ?? 'expired'
       const entry = issued.get(requestId)
       issued.delete(requestId)
-      // A request issued by another process settles in that process.
-      if (entry === undefined) return
-      const agent = agentFor(entry.session)
+      // The transfer made this session an owner by another route, so a later
+      // release notice for the same path would wake it for nothing: the wait is
+      // over because the goal was reached, not because a release happened. The
+      // wait ends BEFORE the outcome is routed, so the cancellation can never be
+      // lost to a cleared route.
+      const session = text(event?.session) ?? entry?.session
+      const path = text(event?.path) ?? entry?.path
+      if (state === 'transferred' && session !== undefined && path !== undefined) {
+        watches.settleSelf(session, path)
+      }
+      // No session and no route: the request was issued in another process.
+      if (session === undefined || path === undefined) return
+      const agent = agentFor(session)
       if (!agent) return
-      const state = text(event?.state) ?? 'expired'
-      notify(agent, settledText(state, requestId, shortName(entry.path, cwdOf(agent))), agent?.status === 'idle')
+      // ONE delivery per request in this process, however many mounts hear this
+      // event — including the mount whose `issued` entry routed it here.
+      if (!claimSettledNotice(agent, requestId)) return
+      notify(agent, settledText(state, requestId, shortName(path, cwdOf(agent))), agent?.status === 'idle')
+    }
+
+    /**
+     * One release fact from the broker (D1/D2).
+     *
+     * Consumption happens inside the coordinator, before anything is scheduled:
+     * the entry leaves the active map in `hit`, so a duplicate or repeated
+     * observation of the same release finds nothing to consume and delivers
+     * nothing. The fact carries no session, so every subscription of this client
+     * for that path is consumed — the arbiter never chooses a winner.
+     * @param {any} event
+     */
+    function onReleased(event) {
+      const path = text(event?.path)
+      if (path !== undefined) watches.consumePath(path)
+    }
+
+    /**
+     * The connection that could have delivered a release is gone (D5).
+     *
+     * Every active subscription ends in `reset` — a terminal state that claims
+     * nothing about ownership — and the coordinator's deferred notice tells each
+     * live subscriber to re-check and re-subscribe, never that the path became
+     * free.
+     */
+    function onConnectionReset() {
+      // A reset also ends the broker incarnation that allocated the request ids
+      // already answered in this process: the next one counts from its own zero.
+      settledEpoch += 1
+      if (disposed) return
+      watches.resetAll()
     }
 
     /** @param {any} event */
@@ -573,17 +767,18 @@ export function createFileLeasePlugin(options = {}) {
       try {
         if (event.event === 'request') await onRequest(event)
         else if (event.event === 'settled') onSettled(event)
+        else if (event.event === 'released') onReleased(event)
       } catch {
         // A listener is a consumer; it must never break the transport.
       }
     }
 
     /**
-     * The tools see the client through this narrow facade for one reason: a
-     * `settled` event carries no session, so the plugin has to remember which
-     * session issued which requestId at the moment the request is made. The
-     * facade adds that bookkeeping and nothing else — every call still ends in
-     * the arbiter.
+     * The tools see the client through this narrow facade for one reason: the
+     * requester of a transfer has to be remembered from the moment the request
+     * is made, because a broker older than `settled.session` pushes the outcome
+     * without naming it. The facade adds that routing memo and nothing else —
+     * every call still ends in the arbiter.
      */
     const routedClient = Object.freeze({
       acquire: (/** @type {any} */ owner, /** @type {any} */ paths, /** @type {any} */ scope) => client.acquire(owner, paths, scope),
@@ -591,6 +786,12 @@ export function createFileLeasePlugin(options = {}) {
       status: (/** @type {any} */ filter) => client.status(filter),
       request: (/** @type {any} */ op, /** @type {any} */ payload) => client.request(op, payload),
       reply: (/** @type {any} */ input) => client.reply(input),
+      // Capability is a property of the CURRENT handshake. A client facade
+      // without the query (an embedder, an older injection) advertises nothing,
+      // so the watch tool fails explicitly instead of waiting for an event that
+      // cannot arrive.
+      supportsEvent: (/** @type {string} */ name) =>
+        typeof client.supportsEvent === 'function' ? client.supportsEvent(name) === true : false,
       requestTransfer: async (/** @type {any} */ path, /** @type {any} */ from) => {
         const reply = await client.requestTransfer(path, from)
         const requestId = text(reply?.requestId)
@@ -603,6 +804,8 @@ export function createFileLeasePlugin(options = {}) {
       client: routedClient,
       ownerOf,
       deliverNotice: (agent, text) => notify(agent, text, false),
+      watchCoordinator: watches,
+      mount: watchMount,
     })
     const replyDefinition = definitions.find((definition) => definition?.name === REPLY_TOOL)
     const staticDefinitions = definitions.filter((definition) => definition?.name !== REPLY_TOOL)
@@ -656,6 +859,18 @@ export function createFileLeasePlugin(options = {}) {
       ctx.logger?.warn?.(`file-lease: negotiation events are unavailable: ${messageOf(error)}`)
     }
 
+    // A vanished broker cannot announce anything, so the reset is a transport
+    // lifecycle signal rather than a wire event (D5). A client without it simply
+    // never reports resets — the other paths still work.
+    /** @type {() => void} */
+    let offReset = () => {}
+    try {
+      const off = typeof client.onReset === 'function' ? client.onReset(() => onConnectionReset()) : undefined
+      if (typeof off === 'function') offReset = off
+    } catch (error) {
+      ctx.logger?.warn?.(`file-lease: transport resets are unavailable: ${messageOf(error)}`)
+    }
+
     /**
      * The arbiter's health as the read-only surface reports it (D13): the client's
      * own connection state, never a fresh probe, so looking cannot change a
@@ -758,6 +973,15 @@ export function createFileLeasePlugin(options = {}) {
       } catch {
         // Already gone.
       }
+      try {
+        offReset()
+      } catch {
+        // Already gone.
+      }
+      // This mount's references leave the shared coordinator. A wait another
+      // mount still owns survives, and a pending notice transfers to a surviving
+      // reference; the last mount's teardown clears everything that is left.
+      watches.leave(watchMount)
       try {
         disposeView()
       } catch {