@semiont/sdk 0.5.4 → 0.5.6

package/dist/index.js

@@ -17,12 +17,27 @@ var StreamObservable = class _StreamObservable extends Observable {
   }
 };
 var CacheObservable = class _CacheObservable extends Observable {
+  /**
+   * Optional one-shot fresh-fetch action. When present, `then()` (the await
+   * path) resolves to a freshly fetched value and rejects on fetch failure —
+   * so a re-read reflects writes (#847). `.subscribe(...)` never uses it: it
+   * keeps the stale-while-revalidate cached view over `source`.
+   */
+  fetchFresh;
   then(onfulfilled, onrejected) {
+    if (this.fetchFresh) {
+      return this.fetchFresh().then(onfulfilled, onrejected);
+    }
     return firstValueFrom(this.pipe(filter((v) => v !== void 0))).then(onfulfilled, onrejected);
   }
   /**
    * Wrap an existing Observable's subscribe behavior in a `CacheObservable`.
    *
+   * `fetchFresh`, when supplied, backs the await path: `await` resolves to a
+   * freshly fetched value (rejecting on failure), so a one-shot read reflects
+   * writes without a scoped subscription (#847). `.subscribe(...)` consumers
+   * keep the SWR view over `source`.
+   *
    * Memoizes on source identity: passing the same `source` returns the same
    * wrapper instance. The Browse cache primitive already returns a stable
    * Observable per key (its B4 contract), so this preserves that contract
@@ -32,10 +47,11 @@ var CacheObservable = class _CacheObservable extends Observable {
    *
    * Backed by a `WeakMap`, so wrappers are GC'd when their source is.
    */
-  static from(source) {
+  static from(source, fetchFresh) {
     let wrapper = wrapperCache.get(source);
     if (!wrapper) {
       wrapper = new _CacheObservable((subscriber) => source.subscribe(subscriber));
+      wrapper.fetchFresh = fetchFresh;
       wrapperCache.set(source, wrapper);
     }
     return wrapper;
@@ -95,7 +111,13 @@ async function busRequest(bus, emitChannel, payload, resultChannel, failureChann
     })
   );
   const resultPromise = firstValueFrom(result$);
-  await bus.emit(emitChannel, fullPayload);
+  try {
+    await bus.emit(emitChannel, fullPayload);
+  } catch (err) {
+    resultPromise.catch(() => {
+    });
+    throw err;
+  }
   const result = await resultPromise;
   if (!result.ok) {
     throw result.error;
@@ -104,25 +126,31 @@ async function busRequest(bus, emitChannel, payload, resultChannel, failureChann
 }
 function createCache(fetchFn) {
   const store$ = new BehaviorSubject(/* @__PURE__ */ new Map());
-  const inflight = /* @__PURE__ */ new Set();
+  const inflight = /* @__PURE__ */ new Map();
   const obsCache = /* @__PURE__ */ new Map();
-  const doFetch = async (key) => {
-    if (inflight.has(key)) return;
-    inflight.add(key);
-    try {
-      const value = await fetchFn(key);
-      const next = new Map(store$.value);
-      next.set(key, value);
-      store$.next(next);
-    } catch {
-    } finally {
-      inflight.delete(key);
-    }
+  const runFetch = (key) => {
+    const existing = inflight.get(key);
+    if (existing) return existing;
+    let p;
+    p = (async () => {
+      try {
+        const value = await fetchFn(key);
+        const next = new Map(store$.value);
+        next.set(key, value);
+        store$.next(next);
+        return value;
+      } finally {
+        if (inflight.get(key) === p) inflight.delete(key);
+      }
+    })();
+    inflight.set(key, p);
+    return p;
   };
   return {
     observe(key) {
       if (!store$.value.has(key) && !inflight.has(key)) {
-        void doFetch(key);
+        void runFetch(key).catch(() => {
+        });
       }
       let obs = obsCache.get(key);
       if (!obs) {
@@ -134,6 +162,9 @@ function createCache(fetchFn) {
       }
       return obs;
     },
+    fetch(key) {
+      return runFetch(key);
+    },
     get(key) {
       return store$.value.get(key);
     },
@@ -142,7 +173,8 @@ function createCache(fetchFn) {
     },
     invalidate(key) {
       inflight.delete(key);
-      void doFetch(key);
+      void runFetch(key).catch(() => {
+      });
     },
     remove(key) {
       const next = new Map(store$.value);
@@ -158,7 +190,8 @@ function createCache(fetchFn) {
     invalidateAll() {
       for (const key of store$.value.keys()) {
         inflight.delete(key);
-        void doFetch(key);
+        void runFetch(key).catch(() => {
+        });
       }
     },
     dispose() {
@@ -193,7 +226,13 @@ var BrowseNamespace = class {
       const result = await busRequest(
         this.transport,
         "browse:resources-requested",
-        { search, archived: filters.archived, limit: filters.limit ?? 100, offset: 0 },
+        {
+          search,
+          archived: filters.archived,
+          entityType: filters.entityType,
+          limit: filters.limit ?? 100,
+          offset: 0
+        },
         "browse:resources-result",
         "browse:resources-failed"
       );
@@ -264,6 +303,9 @@ var BrowseNamespace = class {
     });
     this.subscribeToEvents();
   }
+  transport;
+  bus;
+  content;
   // ── Caches, backed by the RxJS-native `Cache<K, V>` primitive ───────────
   //
   // Each cache encapsulates the BehaviorSubject store, in-flight guard,
@@ -300,18 +342,58 @@ var BrowseNamespace = class {
    * `distinctUntilChanged` at a higher level — would misbehave.
    */
   annotationListObs = /* @__PURE__ */ new Map();
+  /**
+   * Per-source memo for the scope-acquiring wrapper (#847 Phase 4), keyed by
+   * the underlying (stable, per-key) cache observable so the wrapped
+   * observable is itself stable per key — preserving B4/B11 referential
+   * identity through to `CacheObservable.from`'s own memo.
+   */
+  scopedSources = /* @__PURE__ */ new WeakMap();
+  /**
+   * Wrap a resource-scoped live query's source so that *subscribing* acquires
+   * the resource's scope (via the transport's ref-counted
+   * `subscribeToResource`) and the last unsubscribe releases it (#847 Phase 4).
+   * Freshness follows observation: a `.subscribe()` keeps `rId`'s scoped
+   * events flowing — so `mark:*` / entity-tag invalidations reach this cache —
+   * with no separate `subscribeToResource` call from the consumer.
+   *
+   * The one-shot `await` path does NOT go through here (it resolves via the
+   * cache's `fetch` — see `CacheObservable.from`'s `fetchFresh`), so a
+   * one-shot read acquires no scope.
+   *
+   * Memoized per source so the wrapped observable is stable per key (B4/B11).
+   * Each subscription calls `subscribeToResource(rId)`; the transport
+   * ref-counts concurrent subscriptions for the same resource onto a single
+   * SSE scope. Single-scope model unchanged — multi-scope is deferred (see
+   * `.plans/MULTI-RESOURCE-SCOPE.md`).
+   */
+  withScope(rId, source) {
+    let scoped = this.scopedSources.get(source);
+    if (!scoped) {
+      scoped = new Observable((subscriber) => {
+        const release = this.transport.subscribeToResource(rId);
+        const inner = source.subscribe(subscriber);
+        return () => {
+          inner.unsubscribe();
+          release();
+        };
+      });
+      this.scopedSources.set(source, scoped);
+    }
+    return scoped;
+  }
   // ── Live queries ────────────────────────────────────────────────────────
   //
   // These return `CacheObservable<T>`: subscribers see `T | undefined`
   // (with `undefined` during initial load), and `await` resolves to the
   // first non-undefined value.
   resource(resourceId2) {
-    return CacheObservable.from(this.resourceCache.observe(resourceId2));
+    return CacheObservable.from(this.withScope(resourceId2, this.resourceCache.observe(resourceId2)), () => this.resourceCache.fetch(resourceId2));
   }
   resources(filters) {
     const key = JSON.stringify(filters ?? {});
     this.resourceListFilters.set(key, filters ?? {});
-    return CacheObservable.from(this.resourceListCache.observe(key));
+    return CacheObservable.from(this.resourceListCache.observe(key), () => this.resourceListCache.fetch(key));
   }
   annotations(resourceId2) {
     let obs = this.annotationListObs.get(resourceId2);
@@ -319,23 +401,23 @@ var BrowseNamespace = class {
       obs = this.annotationListCache.observe(resourceId2).pipe(map$1((r) => r?.annotations));
       this.annotationListObs.set(resourceId2, obs);
     }
-    return CacheObservable.from(obs);
+    return CacheObservable.from(this.withScope(resourceId2, obs), () => this.annotationListCache.fetch(resourceId2).then((r) => r.annotations));
   }
   annotation(resourceId2, annotationId2) {
     this.annotationResources.set(annotationId2, resourceId2);
-    return CacheObservable.from(this.annotationDetailCache.observe(annotationId2));
+    return CacheObservable.from(this.withScope(resourceId2, this.annotationDetailCache.observe(annotationId2)), () => this.annotationDetailCache.fetch(annotationId2));
   }
   entityTypes() {
-    return CacheObservable.from(this.entityTypesCache.observe(ENTITY_TYPES_KEY));
+    return CacheObservable.from(this.entityTypesCache.observe(ENTITY_TYPES_KEY), () => this.entityTypesCache.fetch(ENTITY_TYPES_KEY));
   }
   tagSchemas() {
-    return CacheObservable.from(this.tagSchemasCache.observe(TAG_SCHEMAS_KEY));
+    return CacheObservable.from(this.tagSchemasCache.observe(TAG_SCHEMAS_KEY), () => this.tagSchemasCache.fetch(TAG_SCHEMAS_KEY));
   }
   referencedBy(resourceId2) {
-    return CacheObservable.from(this.referencedByCache.observe(resourceId2));
+    return CacheObservable.from(this.withScope(resourceId2, this.referencedByCache.observe(resourceId2)), () => this.referencedByCache.fetch(resourceId2));
   }
   events(resourceId2) {
-    return CacheObservable.from(this.resourceEventsCache.observe(resourceId2));
+    return CacheObservable.from(this.withScope(resourceId2, this.resourceEventsCache.observe(resourceId2)), () => this.resourceEventsCache.fetch(resourceId2));
   }
   // ── One-shot reads ──────────────────────────────────────────────────────
   async resourceContent(resourceId2) {
@@ -538,6 +620,8 @@ var MarkNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   async annotation(input) {
     const resourceId2 = resourceId(input.target.source);
     const result = await busRequest(
@@ -563,7 +647,6 @@ var MarkNamespace = class {
       let done = false;
       let pollTimer = null;
       let pollInterval = null;
-      let unsubscribeResource = this.transport.subscribeToResource(resourceId2);
       const cleanup = () => {
         done = true;
         if (pollTimer) {
@@ -574,10 +657,6 @@ var MarkNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
-        if (unsubscribeResource) {
-          unsubscribeResource();
-          unsubscribeResource = null;
-        }
       };
       const resetPollTimer = (jobId) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -647,6 +726,7 @@ var MarkNamespace = class {
           resetPollTimer(jobId);
         }
       }).catch((error) => {
+        if (done) return;
         cleanup();
         subscriber.error(error);
       });
@@ -700,9 +780,14 @@ var MarkNamespace = class {
     const jobType = jobTypeMap[motivation];
     if (!jobType) throw new Error(`Unsupported motivation: ${motivation}`);
     if (motivation === "tagging") {
-      if (!options.schemaId || !options.categories?.length) throw new Error("Tag assist requires schemaId and categories");
+      if (!options.schemaId) {
+        throw new Error('mark.assist with motivation "tagging" requires options.schemaId');
+      }
+      if (!options.categories?.length) {
+        throw new Error('mark.assist with motivation "tagging" requires a non-empty options.categories array');
+      }
     } else if (motivation === "linking") {
-      if (!options.entityTypes?.length) throw new Error("Reference assist requires entityTypes");
+      if (!options.entityTypes?.length) throw new Error('mark.assist with motivation "linking" requires a non-empty entityTypes array');
     }
     const params = {};
     if (options.entityTypes) params.entityTypes = options.entityTypes;
@@ -730,6 +815,8 @@ var BindNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   async body(resourceId2, annotationId2, operations) {
     await this.transport.emit("bind:update-body", {
       correlationId: crypto.randomUUID(),
@@ -747,6 +834,8 @@ var GatherNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   annotation(resourceId2, annotationId2, options) {
     return new StreamObservable((subscriber) => {
       const correlationId = crypto.randomUUID();
@@ -779,6 +868,7 @@ var GatherNamespace = class {
         resourceId: resourceId2,
         options: { contextWindow: options?.contextWindow ?? 2e3 }
       }).catch((error) => {
+        if (subscriber.closed) return;
         subscriber.error(error);
       });
       return () => {
@@ -797,6 +887,8 @@ var MatchNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   requestSearch(input) {
     this.bus.get("match:search-requested").next(input);
   }
@@ -824,6 +916,7 @@ var MatchNamespace = class {
         limit: options?.limit ?? 10,
         useSemanticScoring: options?.useSemanticScoring ?? true
       }).catch((error) => {
+        if (subscriber.closed) return;
         subscriber.error(error);
       });
       return () => {
@@ -839,6 +932,9 @@ var YieldNamespace = class {
     this.bus = bus;
     this.content = content;
   }
+  transport;
+  bus;
+  content;
   resource(data) {
     const totalBytes = typeof Buffer !== "undefined" && data.file instanceof Buffer ? data.file.length : data.file.size;
     return new UploadObservable((subscriber) => {
@@ -891,7 +987,6 @@ var YieldNamespace = class {
       let done = false;
       let pollTimer = null;
       let pollInterval = null;
-      let unsubscribeResource = this.transport.subscribeToResource(resourceId2);
       const cleanup = () => {
         done = true;
         if (pollTimer) {
@@ -902,10 +997,6 @@ var YieldNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
-        if (unsubscribeResource) {
-          unsubscribeResource();
-          unsubscribeResource = null;
-        }
       };
       const resetPollTimer = (jid) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -996,6 +1087,7 @@ var YieldNamespace = class {
           resetPollTimer(jobId);
         }
       }).catch((error) => {
+        if (done) return;
         cleanup();
         subscriber.error(error);
       });
@@ -1047,6 +1139,8 @@ var BeckonNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   attention(resourceId2, annotationId2) {
     void this.transport.emit("beckon:focus", { annotationId: annotationId2, resourceId: resourceId2 });
   }
@@ -1063,6 +1157,7 @@ var FrameNamespace = class {
   constructor(transport) {
     this.transport = transport;
   }
+  transport;
   async addEntityType(type) {
     await this.transport.emit("frame:add-entity-type", { tag: type });
   }
@@ -1082,6 +1177,8 @@ var JobNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   /**
    * Live stream of `job:queued` events. Surfaces a typed view onto the
    * underlying bus channel for consumers (CLIs, MCP handlers, widgets)
@@ -1094,11 +1191,11 @@ var JobNamespace = class {
   get progress$() {
     return this.bus.get("job:report-progress");
   }
-  /** Live stream of `job:complete` events. */
+  /** Live stream of `job:complete` events (global; filter by `jobId`). */
   get complete$() {
     return this.bus.get("job:complete");
   }
-  /** Live stream of `job:fail` events. */
+  /** Live stream of `job:fail` events (global; filter by `jobId`). */
   get fail$() {
     return this.bus.get("job:fail");
   }
@@ -1138,6 +1235,7 @@ var AuthNamespace = class {
   constructor(backend) {
     this.backend = backend;
   }
+  backend;
   async password(emailStr, passwordStr) {
     return this.backend.authenticatePassword(email(emailStr), passwordStr);
   }
@@ -1169,6 +1267,7 @@ var AdminNamespace = class {
   constructor(backend) {
     this.backend = backend;
   }
+  backend;
   async users() {
     const result = await this.backend.listUsers();
     return result.users;
@@ -1291,9 +1390,6 @@ var SemiontClient = class _SemiontClient {
   get state$() {
     return this.transport.state$;
   }
-  subscribeToResource(resourceId2) {
-    return this.transport.subscribeToResource(resourceId2);
-  }
   dispose() {
     this.transport.dispose();
     this.content.dispose();