weir-harness 2.1.1 → 2.1.2

package/src/file-lease/watch.js

@@ -7,7 +7,8 @@
 // notices for one release — and would let one mount's teardown cancel a wait
 // another mount still owns.
 //
-// The coordinator holds three collections and nothing else:
+// The coordinator holds three collections, plus a WeakMap of private episode
+// records keyed by the stable opaque handles handed to callers:
 //
 //   active           one entry per `(session, normalized path)`, in `watching`
 //   pendingDelivery  consumed entries (`hit` / `reset`) whose notice has not
@@ -46,16 +47,54 @@ export const WATCH_STATES = Object.freeze(['watching', 'hit', 'reset', 'self', '
  */
 
 /**
+ * The stable opaque handle returned to callers. Its four public fields are
+ * live, getter-only views; all mutable state lives in the coordinator's WeakMap.
+ *
  * @typedef {object} WatchEntry
  * @property {string} sessionId the session that subscribed
  * @property {string} path normalized absolute path
  * @property {WatchState} state
  * @property {boolean} settledByTool true once a running tool already reported
  *   this episode to the model, so a deferred notice would only repeat it
+ */
+
+/**
+ * The coordinator's structured establishment verdict. Model-facing wording and
+ * presentation metadata stay in tools.js; this vocabulary describes decisions.
+ *
+ * @typedef {object} WatchOutcome
+ * @property {'watching' | 'free' | 'self' | 'released' | 'reset' | 'unsupported' | 'cancelled' | 'transport'} state
+ * @property {any} [holder] the current foreign holder for a watching outcome
+ * @property {unknown} [error] the transport failure for a transport outcome
+ * @property {boolean} [raced] ownership arrived asynchronously while establishing
+ */
+
+/**
+ * The lease-specific facts the coordinator needs to classify a status reply.
+ * The read and capability query remain injected, so this module has no socket.
+ *
+ * @typedef {object} WatchStatusOptions
+ * @property {{ id: string, session: string }} owner the subscribing identity
+ * @property {() => boolean} supportsRelease whether the CURRENT connection
+ *   announces released events
+ */
+
+/**
+ * The private mutable record behind one WatchEntry handle.
+ *
+ * @typedef {object} WatchEpisodeRecord
+ * @property {string} sessionId the session that subscribed
+ * @property {string} path normalized absolute path
+ * @property {WatchState} state
+ * @property {boolean} settledByTool true once a running tool already reported
+ *   this episode to the model, so a deferred notice would only repeat it
  * @property {any} agent the agent that subscribed: delivery re-resolves the
  *   session and refuses to land on a replacement agent
  * @property {Promise<any> | null} statusFlight the ONE authoritative read this
  *   entry is currently sharing, so overlapping calls cannot disagree
+ * @property {Promise<WatchOutcome> | null} establishFlight the ONE complete
+ *   establishment attempt shared by overlapping callers; cleared after watching
+ *   so a later call performs a fresh authoritative read
  * @property {Set<WatchMount>} mounts the mount references that still want it
  * @property {ReturnType<typeof setTimeout> | null} timer the deferred notice
  */
@@ -84,6 +123,11 @@ function unrefTimer(timer) {
   if (typeof handle.unref === 'function') handle.unref()
 }
 
+/** @param {unknown} error @returns {boolean} */
+function isTransport(error) {
+  return error !== null && typeof error === 'object' && /** @type {any} */ (error).code === 'transport'
+}
+
 /**
  * The coordinator surface: one factory is the single definition of what a
  * consumer holds, so the tool surface and the plugin row never re-describe it.
@@ -96,12 +140,25 @@ export function createWatchCoordinator() {
   const pendingDelivery = new Set()
   /** @type {Set<WatchMount>} */
   const mounts = new Set()
+  /** @type {WeakMap<WatchEntry, WatchEpisodeRecord>} */
+  const records = new WeakMap()
 
   /** @param {string} sessionId @param {string} path @returns {string} */
   function keyOf(sessionId, path) {
     return `${sessionId}\u0000${path}`
   }
 
+  /**
+   * Resolve the private record without exposing it on the stable public handle.
+   * @param {WatchEntry} entry
+   * @returns {WatchEpisodeRecord}
+   */
+  function recordOf(entry) {
+    const record = records.get(entry)
+    if (record === undefined) throw new TypeError('Unknown watch episode handle')
+    return record
+  }
+
   /**
    * The public shape of an entry. Internals (mounts, flight, timer, agent
    * identity) stay inside the coordinator.
@@ -109,7 +166,8 @@ export function createWatchCoordinator() {
    * @returns {WatchProjection}
    */
   function project(entry) {
-    return { sessionId: entry.sessionId, path: entry.path, state: entry.state, settledByTool: entry.settledByTool }
+    const record = recordOf(entry)
+    return { sessionId: record.sessionId, path: record.path, state: record.state, settledByTool: record.settledByTool }
   }
 
   /**
@@ -120,16 +178,18 @@ export function createWatchCoordinator() {
    * @returns {WatchMount | undefined}
    */
   function liveMount(entry) {
-    for (const mount of entry.mounts) if (!mount.disposed) return mount
+    const record = recordOf(entry)
+    for (const mount of record.mounts) if (!mount.disposed) return mount
     for (const mount of mounts) if (!mount.disposed) return mount
     return undefined
   }
 
   /** @param {WatchEntry} entry */
   function cancelTimer(entry) {
-    if (entry.timer === null) return
-    clearTimeout(entry.timer)
-    entry.timer = null
+    const record = recordOf(entry)
+    if (record.timer === null) return
+    clearTimeout(record.timer)
+    record.timer = null
   }
 
   /**
@@ -146,7 +206,7 @@ export function createWatchCoordinator() {
    */
   function scheduleNotice(entry) {
     pendingDelivery.add(entry)
-    const flight = entry.statusFlight
+    const flight = recordOf(entry).statusFlight
     if (flight === null) {
       armNotice(entry)
       return
@@ -172,28 +232,29 @@ export function createWatchCoordinator() {
    */
   function armNotice(entry) {
     if (!pendingDelivery.has(entry)) return
-    if (entry.state !== 'hit' && entry.state !== 'reset') {
+    const record = recordOf(entry)
+    if (record.state !== 'hit' && record.state !== 'reset') {
       pendingDelivery.delete(entry)
       return
     }
-    if (entry.timer !== null) return
+    if (record.timer !== null) return
     const timer = setTimeout(() => {
-      entry.timer = null
+      record.timer = null
       pendingDelivery.delete(entry)
-      if (entry.state !== 'hit' && entry.state !== 'reset') return
-      if (entry.settledByTool === true) return
+      if (record.state !== 'hit' && record.state !== 'reset') return
+      if (record.settledByTool === true) return
       const mount = liveMount(entry)
       if (mount === undefined) return
-      const agent = mount.agentFor(entry.sessionId)
+      const agent = mount.agentFor(record.sessionId)
       if (agent === undefined || agent === null) return
-      if (entry.agent !== undefined && agent !== entry.agent) return
+      if (record.agent !== undefined && agent !== record.agent) return
       try {
         mount.notify(entry, agent)
       } catch {
         // A notice is best effort: delivery must never break the transport.
       }
     }, 0)
-    entry.timer = timer
+    record.timer = timer
     unrefTimer(timer)
   }
 
@@ -204,7 +265,7 @@ export function createWatchCoordinator() {
    */
   function endPending(entry, state) {
     if (pendingDelivery.delete(entry)) cancelTimer(entry)
-    entry.state = state
+    recordOf(entry).state = state
   }
 
   /**
@@ -229,12 +290,13 @@ export function createWatchCoordinator() {
     if (!mounts.delete(mount)) return
     mount.disposed = true
     for (const [key, entry] of [...active]) {
-      if (!entry.mounts.delete(mount)) continue
-      if (entry.mounts.size > 0) continue
+      const record = recordOf(entry)
+      if (!record.mounts.delete(mount)) continue
+      if (record.mounts.size > 0) continue
       active.delete(key)
-      entry.state = 'cancelled'
+      record.state = 'cancelled'
     }
-    for (const entry of [...pendingDelivery]) entry.mounts.delete(mount)
+    for (const entry of [...pendingDelivery]) recordOf(entry).mounts.delete(mount)
     if (mounts.size === 0) clear()
   }
 
@@ -253,22 +315,31 @@ export function createWatchCoordinator() {
     const key = keyOf(sessionId, path)
     const known = active.get(key)
     if (known !== undefined) {
-      if (mount !== undefined) known.mounts.add(mount)
-      if (agent !== undefined && agent !== null) known.agent = agent
+      const record = recordOf(known)
+      if (mount !== undefined) record.mounts.add(mount)
+      if (agent !== undefined && agent !== null) record.agent = agent
       return known
     }
-    /** @type {WatchEntry} */
-    const entry = {
+    /** @type {WatchEpisodeRecord} */
+    const record = {
       sessionId,
       path,
       state: 'watching',
       settledByTool: false,
       agent,
       statusFlight: null,
+      establishFlight: null,
       mounts: new Set(),
       timer: null,
     }
-    if (mount !== undefined) entry.mounts.add(mount)
+    const entry = /** @type {WatchEntry} */ (Object.freeze({
+      get sessionId() { return record.sessionId },
+      get path() { return record.path },
+      get state() { return record.state },
+      get settledByTool() { return record.settledByTool },
+    }))
+    records.set(entry, record)
+    if (mount !== undefined) record.mounts.add(mount)
     active.set(key, entry)
     return entry
   }
@@ -292,14 +363,127 @@ export function createWatchCoordinator() {
    * @returns {Promise<any>}
    */
   function shareStatus(entry, run) {
-    if (entry.statusFlight !== null) return entry.statusFlight
+    const record = recordOf(entry)
+    if (record.statusFlight !== null) return record.statusFlight
     /** @type {Promise<any>} */
     const flight = Promise.resolve()
       .then(run)
       .finally(() => {
-        if (entry.statusFlight === flight) entry.statusFlight = null
+        if (record.statusFlight === flight) record.statusFlight = null
       })
-    entry.statusFlight = flight
+    record.statusFlight = flight
+    return flight
+  }
+
+  /** Record that the running tool reported this episode to the model.
+   * @param {WatchEntry} entry
+   */
+  function report(entry) {
+    recordOf(entry).settledByTool = true
+  }
+
+  /**
+   * Reconcile one opaque entry at an await boundary. Terminal facts win over
+   * whatever the authoritative read now says, and `watching` is reserved for
+   * the SAME handle that is still active. Callers never re-implement either
+   * identity rule or mark terminal episodes themselves.
+   *
+   * @param {WatchEntry} entry
+   * @returns {WatchOutcome}
+   */
+  function reconcile(entry) {
+    const record = recordOf(entry)
+    if (record.state === 'hit') {
+      report(entry)
+      return { state: 'released' }
+    }
+    if (record.state === 'reset') {
+      report(entry)
+      return { state: 'reset' }
+    }
+    if (record.state === 'self') {
+      report(entry)
+      return { state: 'self', raced: true }
+    }
+    if (record.state === 'watching' && active.get(keyOf(record.sessionId, record.path)) === entry) {
+      return { state: 'watching' }
+    }
+    return { state: 'cancelled' }
+  }
+
+  /**
+   * Run the complete establishment episode after registration. The read is
+   * shared by shareStatus; every continuation reconciles the same entry before
+   * trusting a reply or failure. Only a plain, still-active wait may be removed
+   * by a late status verdict, and removal is conditional on that exact handle.
+   *
+   * @param {WatchEntry} entry
+   * @param {() => any} run the injected authoritative read
+   * @param {WatchStatusOptions} options
+   * @returns {Promise<WatchOutcome>}
+   */
+  async function establish(entry, run, options) {
+    const record = recordOf(entry)
+    /** @type {any} */
+    let reply
+    try {
+      reply = await shareStatus(entry, run)
+    } catch (error) {
+      const terminal = reconcile(entry)
+      if (terminal.state !== 'watching') return terminal
+      cancel(record.sessionId, record.path, entry)
+      if (isTransport(error)) return { state: 'transport', error }
+      throw error
+    }
+
+    let outcome = reconcile(entry)
+    if (outcome.state !== 'watching') return outcome
+
+    const leases = Array.isArray(reply?.leases) ? reply.leases : []
+    if (leases.length === 0) {
+      cancel(record.sessionId, record.path, entry)
+      return { state: 'free' }
+    }
+
+    const holder = leases[0]?.owner ?? {}
+    const mine = (typeof holder.id === 'string' && holder.id.length > 0 && holder.id === options.owner.id)
+      || (typeof holder.session === 'string' && holder.session.length > 0 && holder.session === options.owner.session)
+    if (mine) {
+      cancel(record.sessionId, record.path, entry, 'self')
+      return { state: 'self' }
+    }
+    if (options.supportsRelease() !== true) {
+      cancel(record.sessionId, record.path, entry)
+      return { state: 'unsupported' }
+    }
+
+    // A capability probe is injectable and may synchronously route an event.
+    // Reconcile once more before claiming that this exact wait is still live.
+    outcome = reconcile(entry)
+    if (outcome.state !== 'watching') return outcome
+    return { state: 'watching', holder }
+  }
+
+  /**
+   * Share the whole establishment attempt, not merely its read. In particular,
+   * two overlapping callers cannot turn one free/unsupported/error verdict into
+   * a second contradictory cancelled verdict. A watching attempt is cleared so
+   * idempotent later calls still refresh the authority; terminal attempts remain
+   * attached only to their private, now-inactive episode record.
+   *
+   * @param {WatchEntry} entry
+   * @param {() => any} run
+   * @param {WatchStatusOptions} options
+   * @returns {Promise<WatchOutcome>}
+   */
+  function status(entry, run, options) {
+    const record = recordOf(entry)
+    if (record.establishFlight !== null) return record.establishFlight
+    /** @type {Promise<WatchOutcome>} */
+    const flight = establish(entry, run, options).finally(() => {
+      if (record.establishFlight === flight && record.state === 'watching') record.establishFlight = null
+    })
+    record.establishFlight = flight
     return flight
   }
 
@@ -321,7 +505,7 @@ export function createWatchCoordinator() {
     if (expected !== undefined && entry !== expected) return undefined
     active.delete(key)
     if (pendingDelivery.delete(entry)) cancelTimer(entry)
-    entry.state = state
+    recordOf(entry).state = state
     return entry
   }
 
@@ -346,7 +530,7 @@ export function createWatchCoordinator() {
     const activeEntry = active.get(key)
     if (activeEntry !== undefined) {
       active.delete(key)
-      activeEntry.state = 'self'
+      recordOf(activeEntry).state = 'self'
       ended = ended ?? activeEntry
     }
     return ended
@@ -364,9 +548,10 @@ export function createWatchCoordinator() {
     /** @type {WatchEntry[]} */
     const consumed = []
     for (const [key, entry] of [...active]) {
-      if (entry.path !== path) continue
+      const record = recordOf(entry)
+      if (record.path !== path) continue
       active.delete(key)
-      entry.state = 'hit'
+      record.state = 'hit'
       scheduleNotice(entry)
       consumed.push(entry)
     }
@@ -383,7 +568,7 @@ export function createWatchCoordinator() {
     const entries = [...active.values()]
     active.clear()
     for (const entry of entries) {
-      entry.state = 'reset'
+      recordOf(entry).state = 'reset'
       scheduleNotice(entry)
     }
     return entries
@@ -399,9 +584,10 @@ export function createWatchCoordinator() {
     /** @type {WatchEntry[]} */
     const cancelled = []
     for (const [key, entry] of [...active]) {
-      if (entry.sessionId !== sessionId) continue
+      const record = recordOf(entry)
+      if (record.sessionId !== sessionId) continue
       active.delete(key)
-      entry.state = 'cancelled'
+      record.state = 'cancelled'
       cancelled.push(entry)
     }
     for (const entry of [...pendingDelivery]) {
@@ -423,7 +609,7 @@ export function createWatchCoordinator() {
     active.clear()
     for (const entry of [...pendingDelivery]) cancelTimer(entry)
     pendingDelivery.clear()
-    for (const entry of entries) entry.state = 'cancelled'
+    for (const entry of entries) recordOf(entry).state = 'cancelled'
     return entries
   }
 
@@ -458,6 +644,9 @@ export function createWatchCoordinator() {
     register,
     peek,
     shareStatus,
+    status,
+    reconcile,
+    report,
     cancel,
     settleSelf,
     consumePath,