@semiont/sdk 0.5.5 → 0.5.7

package/README.md

@@ -87,7 +87,7 @@ const client = new SemiontClient(localTransport, localContentTransport);
 - **Collaboration primitives** — fire-and-forget signals on the verb namespaces (`beckon.hover`, `bind.initiate`, `mark.changeShape`, `browse.click`, ...) coordinate attention and intent across participants. Not afterthoughts, not browser-app fluff: they're how a multi-participant session stays coherent.
 - **Session layer** — `SemiontSession` (per-KB authentication, token refresh, lifecycle), `SemiontBrowser` (multi-KB orchestration), and `SessionStorage` adapters (`InMemorySessionStorage`, plus a browser-backed one in `@semiont/react-ui`).
 - **Flow state machines** — RxJS-based factories (`createMarkStateUnit`, `createGatherStateUnit`, `createMatchStateUnit`, `createYieldStateUnit`, `createBeckonStateUnit`) that wrap each long-running flow with `loading$` / `error$` / progress observables. UI-shape-agnostic — any consumer (browser, terminal, mobile, daemon) can subscribe.
-- **`WorkerBus`** — the transport-neutral channel-bus interface that worker-side adapters consume. Domain-specific worker adapters live with their domain — `createJobClaimAdapter` and `createJobQueueStateUnit` in [`@semiont/jobs`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/jobs); `createSmelterActorStateUnit` in [`@semiont/make-meaning`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/make-meaning) — and consume `WorkerBus` from here.
+- **`WorkerBus`** — the transport-neutral channel-bus interface that worker-side adapters consume. Domain-specific worker adapters live with their domain — `createJobClaimAdapter` in [`@semiont/jobs`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/jobs); `createSmelterActorStateUnit` in [`@semiont/make-meaning`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/make-meaning) — and consume `WorkerBus` from here.
 - **Helpers** — `bus-request` (correlation-ID request/reply), the cache primitive backing live queries, and `createSearchPipeline` (debounced-search RxJS pipeline).
 
 Page-shaped state machines (admin tables, compose page, resource viewer page, etc.) live in [`@semiont/react-ui`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/react-ui), alongside the components that render them. Those are framework-neutral but tied to the Semiont web frontend's specific page taxonomy; they don't apply to non-web consumers.
@@ -104,7 +104,7 @@ Page-shaped state machines (admin tables, compose page, resource viewer page, et
 - The transport-neutral `WorkerBus` interface (worker adapters live in their domain packages — `@semiont/jobs`, `@semiont/make-meaning`)
 - Branded ID types, the unified error hierarchy, the `TransportErrorCode` neutral vocabulary
 
-Nothing page-shaped, nothing web-shell-shaped. A TUI, mobile reader, daemon, or AI agent installs `@semiont/sdk` alone (plus a transport package — `@semiont/api-client` for HTTP, `@semiont/make-meaning` for in-process).
+Nothing page-shaped, nothing web-shell-shaped. A TUI, mobile reader, daemon, or AI agent installs `@semiont/sdk` alone (plus a transport package — `@semiont/http-transport` for HTTP, `@semiont/make-meaning` for in-process).
 
 ## Installation
 
@@ -245,7 +245,7 @@ Apache-2.0 — see [LICENSE](https://github.com/The-AI-Alliance/semiont/blob/mai
 ## Related packages
 
 - [`@semiont/core`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/core) — domain types, `ITransport` contract, OpenAPI-derived schemas
-- [`@semiont/api-client`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/api-client) — HTTP transport (`HttpTransport`, `HttpContentTransport`)
+- [`@semiont/http-transport`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/http-transport) — HTTP transport (`HttpTransport`, `HttpContentTransport`)
 - [`@semiont/make-meaning`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/make-meaning) — in-process transport (`LocalTransport`) and the actor model behind it
 - [`@semiont/observability`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/observability) — OpenTelemetry tracing the SDK propagates across the bus
 - [`@semiont/react-ui`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/react-ui) — React bindings (`useStateUnit`, web `SessionStorage`)

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { firstValueFrom, lastValueFrom } from 'rxjs';
 import * as _semiont_core from '@semiont/core';
 import { ResourceId, components, UserDID, paths, BackendDownload, ProgressEvent, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, TagSchema, GraphConnection, Motivation, GatheredContext, JobId, ITransport, EventBus, IContentTransport, IBackendOperations, BaseUrl, AccessToken, SemiontError, ConnectionState, Selector } from '@semiont/core';
 export { AccessToken, Annotation, AnnotationId, BaseUrl, BodyItem, BodyOperation, ConnectionState, EntityType, EventMap, GatheredContext, IContentTransport, ITransport, Logger, Motivation, RefreshToken, ResourceDescriptor, ResourceId, SemiontError, TagCategory, TagSchema, UserId, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
-export { APIError, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher } from '@semiont/api-client';
+export { APIError, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher } from '@semiont/http-transport';
 
 /**
  * Thenable Observable subclasses.
@@ -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.
@@ -137,6 +152,7 @@ declare class UploadObservable extends Observable<UploadProgress> implements Pro
  */
 
 type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
+type GetResourceResponse$1 = components['schemas']['GetResourceResponse'];
 type GatherProgress = components['schemas']['GatherProgress'];
 type MatchSearchResult = components['schemas']['MatchSearchResult'];
 type JobProgress$2 = components['schemas']['JobProgress'];
@@ -294,6 +310,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>;
@@ -302,15 +319,12 @@ interface BrowseNamespace$1 {
     referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
     events(resourceId: ResourceId): CacheObservable<StoredEventResponse$1[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
-    resourceRepresentation(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
+    resourceGraph(resourceId: ResourceId): Promise<GetResourceResponse$1>;
+    resourceRepresentation(resourceId: ResourceId): Promise<{
         data: ArrayBuffer;
         contentType: string;
     }>;
-    resourceRepresentationStream(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
+    resourceRepresentationStream(resourceId: ResourceId): Promise<{
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
@@ -541,10 +555,12 @@ interface AdminNamespace$1 {
 }
 
 type StoredEventResponse = components['schemas']['StoredEventResponse'];
+type GetResourceResponse = components['schemas']['GetResourceResponse'];
 type ResourceListFilters = {
     limit?: number;
     archived?: boolean;
     search?: string;
+    entityType?: string;
 };
 declare class BrowseNamespace implements BrowseNamespace$1 {
     private readonly transport;
@@ -578,7 +594,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[]>;
@@ -588,15 +630,18 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
     referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
     events(resourceId: ResourceId): CacheObservable<StoredEventResponse[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
-    resourceRepresentation(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
+    /**
+     * Fetch the resource's JSON-LD metadata graph (descriptor + annotations +
+     * inbound entity references). One-shot, uncached, dereferenced via the
+     * transport's HTTP `/jsonld` face (bus-free) — the LD view an external
+     * linked-data client gets. See `.plans/SIMPLER-JSON-LD.md` §5.
+     */
+    resourceGraph(resourceId: ResourceId): Promise<GetResourceResponse>;
+    resourceRepresentation(resourceId: ResourceId): Promise<{
         data: ArrayBuffer;
         contentType: string;
     }>;
-    resourceRepresentationStream(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
+    resourceRepresentationStream(resourceId: ResourceId): Promise<{
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
@@ -768,9 +813,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 +924,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
@@ -1678,7 +1722,7 @@ declare function createSearchPipeline<T>(fetch: (query: string) => Observable<T[
  * (e.g. `JobClaimAdapter` in `@semiont/jobs`, `SmelterActorStateUnit` in
  * `@semiont/make-meaning`) need.
  *
- * Transport-neutral by design. HTTP `ActorStateUnit` (from `@semiont/api-client`)
+ * Transport-neutral by design. HTTP `ActorStateUnit` (from `@semiont/http-transport`)
  * satisfies it directly; an in-process worker can pass a small shim around
  * an `EventBus` with a `() => Promise<void>` `emit` that calls into the
  * actor system.

package/dist/index.js

@@ -1,10 +1,10 @@
-import { SemiontError, annotationId, resourceId, email, googleCredential, refreshToken, EventBus, baseUrl, accessToken, searchQuery } from '@semiont/core';
+import { SemiontError, decodeWithCharset, annotationId, resourceId, email, googleCredential, refreshToken, EventBus, baseUrl, accessToken, searchQuery } from '@semiont/core';
 export { SemiontError, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
 import { Observable, lastValueFrom, firstValueFrom, merge, TimeoutError, throwError, map as map$1, BehaviorSubject, Subject, Subscription, of, distinctUntilChanged as distinctUntilChanged$1 } from 'rxjs';
 export { firstValueFrom, lastValueFrom } from 'rxjs';
 import { filter, map, take, timeout, catchError, takeUntil, startWith, debounceTime, distinctUntilChanged, switchMap } from 'rxjs/operators';
-import { HttpTransport, HttpContentTransport, APIError } from '@semiont/api-client';
-export { APIError, HttpContentTransport, HttpTransport } from '@semiont/api-client';
+import { HttpTransport, HttpContentTransport, APIError } from '@semiont/http-transport';
+export { APIError, HttpContentTransport, HttpTransport } from '@semiont/http-transport';
 
 // src/client.ts
 var StreamObservable = class _StreamObservable extends Observable {
@@ -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,35 +401,43 @@ 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) {
-    const result = await this.content.getBinary(resourceId2, { accept: "text/plain" });
-    const decoder = new TextDecoder();
-    return decoder.decode(result.data);
+    const result = await this.content.getBinary(resourceId2);
+    return decodeWithCharset(result.data, result.contentType);
+  }
+  /**
+   * Fetch the resource's JSON-LD metadata graph (descriptor + annotations +
+   * inbound entity references). One-shot, uncached, dereferenced via the
+   * transport's HTTP `/jsonld` face (bus-free) — the LD view an external
+   * linked-data client gets. See `.plans/SIMPLER-JSON-LD.md` §5.
+   */
+  async resourceGraph(resourceId2) {
+    return this.content.getResourceGraph(resourceId2);
   }
-  async resourceRepresentation(resourceId2, options) {
-    return this.content.getBinary(resourceId2, options?.accept ? { accept: options.accept } : void 0);
+  async resourceRepresentation(resourceId2) {
+    return this.content.getBinary(resourceId2);
   }
-  async resourceRepresentationStream(resourceId2, options) {
-    return this.content.getBinaryStream(resourceId2, options?.accept ? { accept: options.accept } : void 0);
+  async resourceRepresentationStream(resourceId2) {
+    return this.content.getBinaryStream(resourceId2);
   }
   async resourceEvents(resourceId2) {
     const result = await busRequest(
@@ -544,6 +628,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 +655,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 +665,6 @@ var MarkNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
-        if (unsubscribeResource) {
-          unsubscribeResource();
-          unsubscribeResource = null;
-        }
       };
       const resetPollTimer = (jobId) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -742,6 +823,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 +842,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 +895,8 @@ var MatchNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
+  transport;
+  bus;
   requestSearch(input) {
     this.bus.get("match:search-requested").next(input);
   }
@@ -853,6 +940,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 +995,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 +1005,6 @@ var YieldNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
-        if (unsubscribeResource) {
-          unsubscribeResource();
-          unsubscribeResource = null;
-        }
       };
       const resetPollTimer = (jid) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -1062,6 +1147,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 +1165,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 +1185,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 +1199,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 +1243,7 @@ var AuthNamespace = class {
   constructor(backend) {
     this.backend = backend;
   }
+  backend;
   async password(emailStr, passwordStr) {
     return this.backend.authenticatePassword(email(emailStr), passwordStr);
   }
@@ -1184,6 +1275,7 @@ var AdminNamespace = class {
   constructor(backend) {
     this.backend = backend;
   }
+  backend;
   async users() {
     const result = await this.backend.listUsers();
     return result.users;
@@ -1306,9 +1398,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();