watch

Watching tracked scopes and change-tracking consumers. start: this server holds a lease on tracked scope of one source (sourceId when the workspace has several) and the workspace's shared runner refreshes it on each save, so changes shows new revisions without an index call; the server renews its leases every 10 s and ends them when it exits, and an unrenewed lease ends after 30 s. A requestId replays this server's live lease and reports an ended one as ended (untracked when its scope was untracked or retracked since), never restarting it, for 1 h after the end among the newest 1024 ended leases; past that it is unknown and starts a new lease. A requestId of a lease another running process holds is refused. stop ends one lease this server holds (leaseId). status lists the workspace's leases and runner, read-only. ack moves consumer's checkpoint for these filters (sourceId, scope), or a subscription's own (subscriptionId), forward to cursor, the nextCursor of the last changes page it handled with the same filters; an older or equal cursor normally leaves it, so a retry is safe. A cursor issued before retention deleted revisions it had not passed is event_gap, writing nothing: follow its recovery. A current recovery cursor before a checkpoint that is behind such a deletion moves the checkpoint back to it, so the kept revisions replay. Replies with advanced, true only when the checkpoint moved forward, and the checkpoint now held, which is authoritative. subscribe follows one source, scope or exact node (node: a layer id that must name one layer kind in the published index, else target_missing or identity_uncertain, never a same-name layer) from its newest visible revision; a repeat returns the same subscription; owner marks it temporary for that task. subscribe with query (and type) saves a workspace search of one source's scope (default 0:0) and stores its first evaluation of the top 50; evaluate stores a newer one after a publication, and a watch lease on that scope makes its runner store it unasked; changes with its subscriptionId reads the stored evaluations (causes such as source_changed only for new file bytes or index_rebuilt; enteredTopK and leftTopK are exact sourceId/snapshotId/nodeId refs in the new and old snapshot, rankChanged the new snapshot's refs with from and to positions, null when rankComparable is false, all within the top-50 window, not the whole result set; nodes compare by sourceId, which relocate keeps; total only when the search counted every hit) and reports evaluation pending with an evaluate step, never computing one; an evaluation past 128 KiB is unavailable evaluation_too_large, nothing stored. sources (instead of sourceId) saves the search, or a library question (library), over a fixed set: visible resolves once to the sources this caller sees now, or a comma-separated list, at most 10, returned sorted in subscription.sources; it never gains a source added later. A member's publication evaluates it (its runner too); causes source_changed names members with new bytes in delta.changedSourceIds, corpus_changed a member's relocation or publication, or for a ranked search of several members their shared statistics; refs carry their sourceId and snapshot. A library question lists up to 50 uses with definitionMatch against the definition, followed by its exact nodeId in its source's current snapshot (delta.definitionMatchChanged); coverage.transitive is not_followed: a definition's own library dependencies are never traversed, and delta.notFollowedSourceIds names changed members that hold no use and are not the definition's source, whose dependent uses may be stale. A caller who cannot see every member reads the subscription as unknown; removing a member source disables it (state disabled, disabled.reason source_removed, evaluations deleted; a damaged stored set reads disabled with sources_unreadable): unsubscribe, then subscribe again. list pages the visible subscriptions with their state (subscriptionId: only that one, empty when unknown to the caller). unsubscribe removes one subscription and its checkpoint (or, with owner, that owner's temporary ones); forget removes a consumer's raw checkpoint views. Neither untracks or deletes history. A consumer holds at most 64 subscriptions and checkpoints, a workspace 4096: past that, workspace_busy names list, unsubscribe and forget; nothing is evicted.