@semiont/sdk 0.5.5 → 0.5.6

package/dist/index.d.ts

@@ -45,9 +45,12 @@ declare class StreamObservable<T> extends Observable<T> implements PromiseLike<T
  * cache entry. Used by Browse live-query methods (`browse.resource`,
  * `browse.annotations`, etc.).
  *
- * Awaiting resolves to the **first non-undefined** value (waits past the
- * loading state). Subscribing yields the full sequence including the
- * initial `undefined`, so reactive consumers can render a loading state.
+ * Awaiting (the one-shot path) fetches a **fresh** value via the optional
+ * `fetchFresh` action and rejects on failure — a re-read reflects writes
+ * (#847). Subscribing yields the SWR sequence: the initial `undefined`, the
+ * loaded value, and re-emits on invalidation. (Without a `fetchFresh` action
+ * — e.g. a non-cache wrapper — the await falls back to the first
+ * non-undefined emission.)
  *
  * The class is parameterized as `CacheObservable<T>` even though the
  * stream's element type is `T | undefined` — `T` is what the consumer
@@ -56,10 +59,22 @@ declare class StreamObservable<T> extends Observable<T> implements PromiseLike<T
  * `.pipe` in the natural way.
  */
 declare class CacheObservable<T> extends Observable<T | undefined> implements PromiseLike<T> {
+    /**
+     * 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`.
+     */
+    private fetchFresh?;
     then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
     /**
      * 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
@@ -69,7 +84,7 @@ declare class CacheObservable<T> extends Observable<T | undefined> implements Pr
      *
      * Backed by a `WeakMap`, so wrappers are GC'd when their source is.
      */
-    static from<T>(source: Observable<T | undefined>): CacheObservable<T>;
+    static from<T>(source: Observable<T | undefined>, fetchFresh?: () => Promise<T>): CacheObservable<T>;
 }
 /**
  * Discriminated phases of an upload's lifecycle.
@@ -294,6 +309,7 @@ interface BrowseNamespace$1 {
         limit?: number;
         archived?: boolean;
         search?: string;
+        entityType?: string;
     }): CacheObservable<ResourceDescriptor[]>;
     annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
     annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
@@ -545,6 +561,7 @@ type ResourceListFilters = {
     limit?: number;
     archived?: boolean;
     search?: string;
+    entityType?: string;
 };
 declare class BrowseNamespace implements BrowseNamespace$1 {
     private readonly transport;
@@ -578,7 +595,33 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
      * `distinctUntilChanged` at a higher level — would misbehave.
      */
     private readonly annotationListObs;
+    /**
+     * 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.
+     */
+    private readonly scopedSources;
     constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
+    /**
+     * 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`).
+     */
+    private withScope;
     resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
     resources(filters?: ResourceListFilters): CacheObservable<ResourceDescriptor[]>;
     annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
@@ -768,9 +811,9 @@ declare class JobNamespace implements JobNamespace$1 {
     get queued$(): Observable<EventMap['job:queued']>;
     /** Live stream of `job:report-progress` events. */
     get progress$(): Observable<EventMap['job:report-progress']>;
-    /** Live stream of `job:complete` events. */
+    /** Live stream of `job:complete` events (global; filter by `jobId`). */
     get complete$(): Observable<EventMap['job:complete']>;
-    /** Live stream of `job:fail` events. */
+    /** Live stream of `job:fail` events (global; filter by `jobId`). */
     get fail$(): Observable<EventMap['job:fail']>;
     status(jobId: JobId): Promise<JobStatusResponse>;
     pollUntilComplete(jobId: JobId, options?: {
@@ -879,7 +922,6 @@ declare class SemiontClient {
     constructor(transport: ITransport, content: IContentTransport, backend?: IBackendOperations);
     /** Transport-level connection state. HTTP reflects SSE health; local is always 'connected'. */
     get state$(): rxjs.Observable<_semiont_core.ConnectionState>;
-    subscribeToResource(resourceId: ResourceId): () => void;
     dispose(): void;
     /**
      * Convenience factory for the default HTTP setup. Constructs a

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;
@@ -110,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) {
@@ -140,6 +162,9 @@ function createCache(fetchFn) {
       }
       return obs;
     },
+    fetch(key) {
+      return runFetch(key);
+    },
     get(key) {
       return store$.value.get(key);
     },
@@ -148,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);
@@ -164,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() {
@@ -199,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"
       );
@@ -270,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,
@@ -306,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);
@@ -325,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) {
@@ -544,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(
@@ -569,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) {
@@ -580,10 +657,6 @@ var MarkNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
-        if (unsubscribeResource) {
-          unsubscribeResource();
-          unsubscribeResource = null;
-        }
       };
       const resetPollTimer = (jobId) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -742,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(),
@@ -759,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();
@@ -810,6 +887,8 @@ var MatchNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   requestSearch(input) {
     this.bus.get("match:search-requested").next(input);
   }
@@ -853,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) => {
@@ -905,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) {
@@ -916,10 +997,6 @@ var YieldNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
-        if (unsubscribeResource) {
-          unsubscribeResource();
-          unsubscribeResource = null;
-        }
       };
       const resetPollTimer = (jid) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -1062,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 });
   }
@@ -1078,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 });
   }
@@ -1097,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)
@@ -1109,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");
   }
@@ -1153,6 +1235,7 @@ var AuthNamespace = class {
   constructor(backend) {
     this.backend = backend;
   }
+  backend;
   async password(emailStr, passwordStr) {
     return this.backend.authenticatePassword(email(emailStr), passwordStr);
   }
@@ -1184,6 +1267,7 @@ var AdminNamespace = class {
   constructor(backend) {
     this.backend = backend;
   }
+  backend;
   async users() {
     const result = await this.backend.listUsers();
     return result.users;
@@ -1306,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();