@semiont/sdk 0.5.2 → 0.5.4

package/README.md

@@ -14,9 +14,9 @@ The SDK is **transport-agnostic**: it consumes the `ITransport` and `IContentTra
 
 > **Where this doc fits.** This README is the *typed-surface reference* — what's in `@semiont/sdk`, how the namespaces are organized, what return shapes to expect. For the *protocol-level architectural framing* (the eight flows, the three programmable surfaces — CLI, SDK, Skills — the core tenets, the per-flow contracts), start with [`docs/protocol/README.md`](https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/README.md). Daemon authors stitching multiple packages together also want the [skill packs](https://github.com/The-AI-Alliance/semiont/tree/main/docs/protocol/skills) — `semiont-session` for watcher daemons, `semiont-worker` for job-claim daemons, `semiont-wiki` for the end-to-end annotation pipeline.
 
-## Three ideas that hold the surface together
+## Four ideas that hold the surface together
 
-The SDK is wider than a typical client library because the domain is — collaborative knowledge work over a shared corpus, with humans and AI agents as peers. Three framings make the API tractable; once you've seen them, the rest is predictable.
+The SDK is wider than a typical client library because the domain is — collaborative knowledge work over a shared corpus, with humans and AI agents as peers. Four framings make the API tractable; once you've seen them, the rest is predictable.
 
 ### 1. Eight verbs
 
@@ -24,38 +24,62 @@ Every operation in the SDK belongs to one of eight *flows* — verbs that descri
 
 | Verb | What it does | Example methods |
 |---|---|---|
-| **frame** | Define and evolve the schema vocabulary (entity types, future tag schemas, relation types) | `frame.addEntityType`, `frame.addEntityTypes` |
+| **frame** | Define and evolve the schema vocabulary (entity types, tag schemas, future relation types) | `frame.addEntityType`, `frame.addEntityTypes`, `frame.addTagSchema` |
 | **yield** | Introduce new resources into the system | `yield.resource`, `yield.fromAnnotation`, `yield.cloneToken` |
 | **mark** | Add structured metadata to resources | `mark.annotation`, `mark.assist`, `mark.archive` |
 | **match** | Search the corpus for candidate resources | `match.search` |
 | **bind** | Resolve ambiguous references to specific resources | `bind.body`, `bind.initiate` |
 | **gather** | Assemble related context around an annotation | `gather.annotation` |
-| **browse** | Navigate, read, and observe | `browse.resource`, `browse.annotations`, `browse.click` |
+| **browse** | Navigate, read, and observe | `browse.resource`, `browse.annotations`, `browse.entityTypes`, `browse.tagSchemas`, `browse.click` |
 | **beckon** | Coordinate attention across participants | `beckon.hover`, `beckon.attention`, `beckon.sparkle` |
 
 Each flow is a namespace on `SemiontClient` (`client.mark.X(...)`, `client.gather.X(...)`, ...). The verb is the unit of mental model — a method call belongs to a flow, not to a noun. Frame is the schema-layer flow — content flows operate within the vocabulary Frame manages. Per-flow contracts live in [`docs/protocol/flows`](https://github.com/The-AI-Alliance/semiont/tree/main/docs/protocol/flows).
 
-### 2. Four return shapes — guess from the name
+### 2. One call, two ways to consume
 
-Every method on every namespace returns one of exactly four shapes, and the method name tells you which. Internalize the convention once and you stop having to read return types:
+Most data-fetching libraries make you choose between Promise-shaped and Observable-shaped at the import line. The SDK doesn't. Every long-lived value comes back as an `Observable` that *also* implements `PromiseLike<T>` — `await` it for the final value, `.subscribe(...)` it for progress events or live updates, from the same call.
 
-| Shape | Naming convention | Examples |
-|---|---|---|
-| **`Promise<T>`** — atomic backend op | past-tense or short noun | `mark.annotation`, `bind.body`, `auth.password` |
-| **`StreamObservable<T>`** — long-running stream | plain verb | `mark.assist`, `match.search`, `gather.annotation` |
-| **`CacheObservable<T>`** — live query | plain noun | `browse.resource`, `browse.annotations`, `browse.entityTypes` |
-| **`void`** — collaboration signal | imperative or progressive verb | `beckon.hover`, `bind.initiate`, `mark.changeShape` |
+```ts
+// One-shot consumer — never imports rxjs
+const resource = await client.browse.resource(rId);
+const result   = await client.match.search(rId, refId, ctx);
+
+// Reactive consumer — same call, .subscribe instead of await
+client.browse.resource(rId).subscribe((r) => {
+  if (r === undefined) showSkeleton();
+  else render(r);
+});
+client.match.search(rId, refId, ctx).subscribe((event) => {
+  if (event.kind === 'progress') updateProgress(event.data);
+});
+```
+
+A script that just wants the final value never imports anything from `rxjs`. A browser app rendering loading state subscribes to the same shape. The reactive substrate is preserved as a load-bearing architectural choice; the user-facing surface looks Promise-shaped when that's all the caller needs.
 
-Both Observable subclasses implement `PromiseLike<T>`, so consumers can `await` them directly without learning RxJS. Reach for `.subscribe(...)` when you want progress events, live updates, or to observe a collaboration signal another participant emitted. See [`docs/REACTIVE-MODEL.md`](https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/docs/REACTIVE-MODEL.md) for the full design and method-by-method assignment.
+Methods return one of: `Promise<T>` (atomic backend ops), an awaitable `Observable<T>` subclass (`StreamObservable<T>` for bounded progress streams, `CacheObservable<T>` for live queries with stale-while-revalidate), or `void` (collaboration signals — see #3). Per-method assignments and the typing discipline are in [`docs/REACTIVE-MODEL.md`](https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/docs/REACTIVE-MODEL.md).
 
 ### 3. Collaboration primitives
 
-The fourth row above — the `void`-returning collaboration signals — is the SDK's distinctive contribution to multi-participant coordination. They look fire-and-forget at the call site; on the bus they fan out across every participant.
+The `void`-returning third category — collaboration signals — is the SDK's distinctive contribution to multi-participant coordination. They look fire-and-forget at the call site; on the bus they fan out across every participant.
 
 A human in a browser hovers an annotation (`beckon.hover(annotationId)`); an AI agent at the other end of the bus sees `beckon:hover` and reacts. An agent emits a sparkle (`beckon.sparkle(annotationId)`); the human's UI lights up the indicated annotation. A frontend state unit emits `mark.changeShape('rectangle')`; a different participant subscribed to `mark:shape-changed` reacts.
 
 This is *protocol-level* coordination — not browser-app fluff, not bolted-on presence — and it sits on the same typed namespace surface as data operations. Observers reach the same signals via `session.subscribe(channel, handler)` or `client.bus.get(channel)`. Three legitimate paths to the bus are documented in [`docs/REACTIVE-MODEL.md`](https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/docs/REACTIVE-MODEL.md#three-paths-to-the-bus).
 
+### 4. Transport agnosticism
+
+`SemiontClient` is constructed against the `ITransport` and `IContentTransport` interfaces from `@semiont/core` — not against any particular wire. The same SDK surface runs over HTTP, in-process, or any future transport that satisfies the interface. None of the eight verb namespaces or the flow state machines reach for transport-specific features.
+
+```ts
+// HTTP — connect to a remote backend
+const client = await SemiontClient.signInHttp({ baseUrl, email, password });
+
+// In-process — same surface, no network
+const client = new SemiontClient(localTransport, localContentTransport);
+```
+
+`KnowledgeBase` carries a uniform shape regardless of transport (only the nested `endpoint` varies — `{ kind: 'http', host, port, protocol }` or `{ kind: 'local', kbId }`). Code that doesn't *construct* transports — your scripts, the verb namespaces, the flow state machines — never inspects which kind it has. Tests can run against an in-process transport for speed; daemons can embed the backend; the same domain code drives both.
+
 ## What's in the box
 
 - **`SemiontClient`** — the verb-oriented coordinator over a wire transport.
@@ -166,7 +190,7 @@ Same `SemiontClient`, same verb namespaces — no network involved. There is no
 
 ## Worked examples
 
-The eight verb namespaces hang off `SemiontClient`, plus three infrastructure namespaces (`auth`, `admin`, `job`) when the client was constructed with backend operations. Each example below uses one of the four return shapes from the table above; pick whichever matches what your call site needs.
+The eight verb namespaces hang off `SemiontClient`, plus three infrastructure namespaces (`auth`, `admin`, `job`) when the client was constructed with backend operations. Each example below uses one of the return shapes mentioned above; the per-method assignment table is in [`docs/REACTIVE-MODEL.md`](https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/docs/REACTIVE-MODEL.md#method-by-method-assignment).
 
 ```ts
 // Browse — live queries; await yields the loaded value, subscribe yields

package/dist/awaitable.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Thenable Observable subclasses.
+ *
+ * Two thin Observable subclasses that also implement `PromiseLike<T>`. Used as
+ * the public return type of namespace methods that emit streams (job
+ * lifecycle, generation progress) and cache reads (Browse live queries).
+ *
+ * The point: scripts can `await` the call directly without `lastValueFrom` /
+ * `firstValueFrom` wrappers; reactive consumers keep using `.subscribe(...)`
+ * and `.pipe(...)` exactly as before.
+ *
+ * The asymmetric `.then()` semantics — last-value-on-completion for streams,
+ * first-non-undefined-value for caches — is encoded by the subclass name. The
+ * docstring on the namespace method tells the consumer which one applies.
+ *
+ * `.pipe(...)` returns a plain `Observable<T>` (RxJS doesn't propagate
+ * subclasses through `pipe`). Once you compose, you've explicitly entered
+ * RxJS land; `lastValueFrom` from `rxjs` is the right bridge there.
+ */
+import { Observable } from 'rxjs';
+import type { ResourceId } from '@semiont/core';
+/**
+ * Bounded Observable stream — emits zero-or-more progress values, then a
+ * final value on completion. Used by job-lifecycle methods like
+ * `mark.assist`, `gather.annotation`, `match.search`, `yield.fromAnnotation`.
+ *
+ * Awaiting resolves to the **last** emitted value (via `lastValueFrom`).
+ * Subscribing yields every emission, ending in `complete`.
+ */
+export declare class StreamObservable<T> extends Observable<T> implements PromiseLike<T> {
+    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 StreamObservable. */
+    static from<T>(source: Observable<T>): StreamObservable<T>;
+}
+/**
+ * Multicast cache observable — emits `undefined` while the underlying value
+ * is loading, then the value, then re-emits when bus events invalidate the
+ * 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.
+ *
+ * The class is parameterized as `CacheObservable<T>` even though the
+ * stream's element type is `T | undefined` — `T` is what the consumer
+ * gets from `await`, and that's the contract we want to advertise. The
+ * `Observable<T | undefined>` shape leaks through `.subscribe` and
+ * `.pipe` in the natural way.
+ */
+export declare class CacheObservable<T> extends Observable<T | undefined> implements PromiseLike<T> {
+    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`.
+     *
+     * 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
+     * through the awaitable wrapping. Without the memo, every public-method
+     * call would produce a fresh wrapper and break referential-equality
+     * guarantees that hook-style reactive consumers depend on.
+     *
+     * Backed by a `WeakMap`, so wrappers are GC'd when their source is.
+     */
+    static from<T>(source: Observable<T | undefined>): CacheObservable<T>;
+}
+/**
+ * Discriminated phases of an upload's lifecycle.
+ *
+ * - `started` — emitted immediately on `yield.resource(...)` invocation, before any bytes flow.
+ * - `progress` — emitted as bytes flow over the wire. Wired by `HttpContentTransport`'s XHR path when a caller passes `onProgress` (or, transitively, when `yield.resource` is the caller — it always wires the hook so subscribers see byte counts). `bytesUploaded` and `totalBytes` carry the running counts; `totalBytes` may be 0 when the transport can't determine the total (rare, e.g. chunked encoding) — UI consumers should render an indeterminate state in that case.
+ * - `finished` — emitted on backend acknowledgement, carries the assigned `resourceId`.
+ *
+ * Failures surface as `Observable.error(...)` (typically an `APIError` from the transport's `errors$` Subject), not as a `phase: 'failed'` event — `subscribe`'s error callback handles them. Cancellation is honored: unsubscribing before `finished` aborts the in-flight HTTP request on the XHR path.
+ */
+export type UploadProgress = {
+    phase: 'started';
+    totalBytes: number;
+} | {
+    phase: 'progress';
+    bytesUploaded: number;
+    totalBytes: number;
+} | {
+    phase: 'finished';
+    resourceId: ResourceId;
+};
+/**
+ * Specialized `StreamObservable` for `yield.resource`. Subscribers see the
+ * full `UploadProgress` event sequence (started → optional progress → finished).
+ * Awaiting resolves specifically to `{ resourceId }` extracted from the
+ * `'finished'` event — preserving the pre-Phase-18 awaited shape so existing
+ * `await client.yield.resource(...)` callers don't need to narrow the union.
+ */
+export declare class UploadObservable extends Observable<UploadProgress> implements PromiseLike<{
+    resourceId: ResourceId;
+}> {
+    then<R1 = {
+        resourceId: ResourceId;
+    }, R2 = never>(onfulfilled?: ((v: {
+        resourceId: ResourceId;
+    }) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+}
+//# sourceMappingURL=awaitable.d.ts.map

package/dist/awaitable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awaitable.d.ts","sourceRoot":"","sources":["../src/awaitable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAiC,MAAM,MAAM,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;GAOG;AACH,qBAAa,gBAAgB,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAC9E,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,KAAK,EACrB,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EACrD,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,GACzD,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;IAIvB,8EAA8E;IAC9E,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC;CAG3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,GAAG,SAAS,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IACzF,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,KAAK,EACrB,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EACrD,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,GACzD,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;IAKvB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;CAQtE;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC;AAElD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,UAAU,CAAC,cAAc,CAAE,YAAW,WAAW,CAAC;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC;IACjH,IAAI,CAAC,EAAE,GAAG;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,EAAE,EAAE,GAAG,KAAK,EAC9C,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EAC9E,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,GACzD,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;CASxB"}

package/dist/bus-request.d.ts

@@ -0,0 +1,18 @@
+import { Observable } from 'rxjs';
+import { SemiontError, type EventMap } from '@semiont/core';
+export type BusRequestErrorCode = 'bus.timeout' | 'bus.rejected' | 'bus.bad-payload' | 'bus.unauthorized' | 'bus.forbidden' | 'bus.not-found';
+export declare class BusRequestError extends SemiontError {
+    code: BusRequestErrorCode;
+    constructor(message: string, code: BusRequestErrorCode, details?: Record<string, unknown>);
+}
+/**
+ * Subset of ITransport that `busRequest` needs: a way to send a command and
+ * a way to observe channels. Generic enough that an in-process transport
+ * can satisfy it without round-tripping through HTTP.
+ */
+export interface BusRequestPrimitive {
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): Promise<void>;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+}
+export declare function busRequest<TResult>(bus: BusRequestPrimitive, emitChannel: string, payload: Record<string, unknown>, resultChannel: string, failureChannel: string, timeoutMs?: number): Promise<TResult>;
+//# sourceMappingURL=bus-request.d.ts.map

package/dist/bus-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus-request.d.ts","sourceRoot":"","sources":["../src/bus-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmD,MAAM,MAAM,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,eAAe,CAAC;AAEpB,qBAAa,eAAgB,SAAQ,YAAY;IACvC,IAAI,EAAE,mBAAmB,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI1F;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,MAAM,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,OAAO,EAAE,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CACvE;AAED,wBAAsB,UAAU,CAAC,OAAO,EACtC,GAAG,EAAE,mBAAmB,EACxB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,SAAS,SAAS,GACjB,OAAO,CAAC,OAAO,CAAC,CA+ClB"}

package/dist/cache.d.ts

@@ -0,0 +1,57 @@
+/**
+ * RxJS-native read-through cache primitive.
+ *
+ * Behavioral contract: packages/sdk/docs/CACHE-SEMANTICS.md (B1–B13).
+ *
+ * Framework-agnostic: no React, no dependency on any namespace. Used by
+ * `BrowseNamespace` to back its per-key stores, but equally usable from
+ * CLI, MCP, or worker code.
+ *
+ * Shape:
+ *   - `observe(key)`: returns an Observable<V | undefined> that triggers
+ *     a fetch on first subscription for a missing key, dedup-joins any
+ *     concurrent fetch, and emits the stored value thereafter.
+ *   - `invalidate(key)`: stale-while-revalidate — keeps the current
+ *     value visible to observers, clears the in-flight guard, starts a
+ *     fresh fetch. If the previous fetch was orphaned (SSE torn down,
+ *     response lost), this is how the cache recovers.
+ *   - `remove(key)`: drops the cache entry entirely. Used for entity
+ *     deletions (B13a). No refetch.
+ *   - `set(key, value)`: writes through without a fetch. Used when a
+ *     bus event carries the new value inline (B13b).
+ *   - `invalidateAll()`: per-key SWR refetch of every currently-cached
+ *     entry. Used by gap-detection paths.
+ *   - `dispose()`: completes the store so observers unsubscribe.
+ *
+ * What's deliberately out:
+ *   - No subscriber ref-counting / GC of unobserved keys. The per-key
+ *     observable memo grows with the set of observed keys for the cache's
+ *     lifetime (B11). Acceptable given cache lifetime == client lifetime.
+ *   - No TTL / cacheTime. Entries are evicted only by explicit remove.
+ *   - No retry / backoff. A failing fetch leaves the cache unchanged
+ *     (B6); the caller drives retry via invalidate.
+ */
+import { Observable } from 'rxjs';
+export interface Cache<K, V> {
+    /** Observable stream of the value at `key`. Triggers a fetch if not cached. */
+    observe(key: K): Observable<V | undefined>;
+    /** Synchronous snapshot of the current value, without triggering a fetch. */
+    get(key: K): V | undefined;
+    /** Iterator of currently-cached keys. For invalidateAll and diagnostics. */
+    keys(): K[];
+    /**
+     * Mark the entry stale and refetch. Keeps the previous value visible
+     * to observers during the refetch (stale-while-revalidate).
+     */
+    invalidate(key: K): void;
+    /** Drop the entry from the cache. No refetch. */
+    remove(key: K): void;
+    /** Write-through: set the value directly without a fetch. */
+    set(key: K, value: V): void;
+    /** Per-key SWR refetch of every currently-cached entry. */
+    invalidateAll(): void;
+    /** Release the underlying subject. Observers complete. */
+    dispose(): void;
+}
+export declare function createCache<K, V>(fetchFn: (key: K) => Promise<V>): Cache<K, V>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAmB,UAAU,EAA6B,MAAM,MAAM,CAAC;AAE9E,MAAM,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAE3B,4EAA4E;IAC5E,IAAI,IAAI,CAAC,EAAE,CAAC;IAEZ;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAEzB,iDAAiD;IACjD,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAErB,6DAA6D;IAC7D,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE5B,2DAA2D;IAC3D,aAAa,IAAI,IAAI,CAAC;IAEtB,0DAA0D;IAC1D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CA0F9E"}

package/dist/client.d.ts

@@ -0,0 +1,138 @@
+/**
+ * SemiontClient — the verb-oriented namespace surface.
+ *
+ * Thin coordinator over an injected transport pair. Owns a local
+ * `EventBus` (`bus`) for UI-signal channels and bridges wire events into
+ * it via `transport.bridgeInto(bus)`. Namespaces receive `(transport,
+ * bus)` (and `content` for binary-I/O namespaces) and choose internally
+ * whether each method goes over the wire or stays local.
+ *
+ * No public `emit`/`on`/`stream` shortcuts: consumers call typed
+ * namespace methods. The single sanctioned channel-by-name escape hatch
+ * is `SemiontSession.subscribe(channel, handler)`, which reads from
+ * `client.bus`.
+ */
+import type { ResourceId, BaseUrl, AccessToken } from '@semiont/core';
+import { EventBus } from '@semiont/core';
+import { BrowseNamespace } from './namespaces/browse';
+import { MarkNamespace } from './namespaces/mark';
+import { BindNamespace } from './namespaces/bind';
+import { GatherNamespace } from './namespaces/gather';
+import { MatchNamespace } from './namespaces/match';
+import { YieldNamespace } from './namespaces/yield';
+import { BeckonNamespace } from './namespaces/beckon';
+import { FrameNamespace } from './namespaces/frame';
+import { JobNamespace } from './namespaces/job';
+import { AuthNamespace } from './namespaces/auth';
+import { AdminNamespace } from './namespaces/admin';
+import type { IBackendOperations, IContentTransport, ITransport } from '@semiont/core';
+export { APIError, type TokenRefresher, HttpTransport, type HttpTransportConfig, HttpContentTransport, } from '@semiont/api-client';
+export declare class SemiontClient {
+    /**
+     * The wire-facing transport. Owns bus actor, HTTP, auth, admin, exchange,
+     * system. Exposed for advanced consumers (workers, custom job adapters)
+     * that need raw `transport.emit(channel, payload, scope)` access. Ordinary
+     * consumers go through typed namespace methods.
+     */
+    readonly transport: ITransport;
+    /** Binary I/O transport. */
+    private readonly content;
+    /**
+     * Per-client local EventBus. Wire events flow in via the transport
+     * bridge. Read-only public so `SemiontSession.subscribe(channel, …)`
+     * can wire arbitrary-channel subscriptions; everything else uses
+     * typed namespace methods.
+     */
+    readonly bus: EventBus;
+    readonly baseUrl: BaseUrl;
+    readonly frame: FrameNamespace;
+    readonly browse: BrowseNamespace;
+    readonly mark: MarkNamespace;
+    readonly bind: BindNamespace;
+    readonly gather: GatherNamespace;
+    readonly match: MatchNamespace;
+    readonly yield: YieldNamespace;
+    readonly beckon: BeckonNamespace;
+    readonly job: JobNamespace;
+    readonly auth: AuthNamespace | undefined;
+    readonly admin: AdminNamespace | undefined;
+    /**
+     * The client *owns* its bus. The constructor creates a fresh `EventBus`
+     * and hands it to the transport via `transport.bridgeInto(this.bus)`.
+     * The reference flows client → transport, never the other way:
+     * the transport stores the reference and publishes the events it
+     * receives onto that bus. `HttpTransport` does so for every channel
+     * delivered on its SSE wire; in-process transports adapt their
+     * internal source.
+     *
+     * Callers do not pass a bus in. If they need to interact with the bus
+     * (e.g. for tests or to subscribe to arbitrary channels), they read it
+     * back via `client.bus`.
+     *
+     * `backend` is optional. When provided, the `auth` and `admin`
+     * namespaces are constructed against it; when omitted, they're
+     * `undefined`. For HTTP setups this is conventionally the same
+     * `HttpTransport` instance that's also passed as `transport` (HTTP
+     * implements both `ITransport` and `IBackendOperations`).
+     */
+    constructor(transport: ITransport, content: IContentTransport, backend?: IBackendOperations);
+    /** Transport-level connection state. HTTP reflects SSE health; local is always 'connected'. */
+    get state$(): import("rxjs").Observable<import("@semiont/core").ConnectionState>;
+    subscribeToResource(resourceId: ResourceId): () => void;
+    dispose(): void;
+    /**
+     * Convenience factory for the default HTTP setup. Constructs a
+     * `BehaviorSubject<AccessToken | null>` internally, plus an
+     * `HttpTransport` and `HttpContentTransport`, and returns the wired
+     * `SemiontClient`.
+     *
+     * Use this for one-shot scripts, CLI commands, or any consumer that
+     * doesn't need to drive the token from outside (no manual refresh,
+     * no cross-tab sync). For long-running scripts that need refresh,
+     * use `SemiontSession.fromHttp(...)` (with a token already on hand)
+     * or `SemiontSession.signInHttp(...)` (credentials-first) instead —
+     * either owns the same transport/client wiring plus the
+     * proactive-refresh + storage machinery.
+     *
+     * Strings are accepted for `baseUrl` and `token`; they are branded
+     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
+     * Pass the already-branded values if you have them.
+     *
+     * Omit `token` for unauthenticated usage (public endpoints only).
+     */
+    static fromHttp(opts: {
+        baseUrl: BaseUrl | string;
+        token?: AccessToken | string | null;
+    }): SemiontClient;
+    /**
+     * Async factory for the credentials-first script case. Builds a
+     * transient HTTP transport, calls `auth.password(email, password)`
+     * to acquire an access token, and returns the wired client with
+     * the token populated.
+     *
+     * This is the right entry point for skills, CLI scripts, and any
+     * consumer that starts with email + password rather than a JWT
+     * already on hand. For consumers that already hold a token (CLI
+     * cached-token path, env-var token, embedded auth flow), use
+     * `fromHttp({ baseUrl, token })` instead.
+     *
+     * For long-running scripts that need refresh, use
+     * `SemiontSession.signInHttp(...)` — same credentials shape, plus
+     * the session machinery for proactive refresh and persistence.
+     *
+     * Named `signInHttp` because email+password authentication is
+     * inherently an HTTP-shaped operation in the current backend; an
+     * in-process `LocalTransport` doesn't have a credentials login
+     * path. Non-HTTP transports construct the client directly from
+     * their package's transport instance.
+     *
+     * Throws if authentication fails. The transient client is disposed
+     * before the throw, so no resources leak on failure.
+     */
+    static signInHttp(opts: {
+        baseUrl: BaseUrl | string;
+        email: string;
+        password: string;
+    }): Promise<SemiontClient>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAevF,OAAO,EACL,QAAQ,EACR,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,qBAAa,aAAa;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAW1B,SAAgB,KAAK,EAAE,cAAc,CAAC;IACtC,SAAgB,MAAM,EAAE,eAAe,CAAC;IACxC,SAAgB,IAAI,EAAE,aAAa,CAAC;IACpC,SAAgB,IAAI,EAAE,aAAa,CAAC;IACpC,SAAgB,MAAM,EAAE,eAAe,CAAC;IACxC,SAAgB,KAAK,EAAE,cAAc,CAAC;IACtC,SAAgB,KAAK,EAAE,cAAc,CAAC;IACtC,SAAgB,MAAM,EAAE,eAAe,CAAC;IACxC,SAAgB,GAAG,EAAE,YAAY,CAAC;IAClC,SAAgB,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChD,SAAgB,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC;IAElD;;;;;;;;;;;;;;;;;;OAkBG;gBACS,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,kBAAkB;IAqB3F,+FAA+F;IAC/F,IAAI,MAAM,uEAET;IAED,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,IAAI;IAIvD,OAAO,IAAI,IAAI;IAKf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QACpB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;KACrC,GAAG,aAAa;IAajB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACU,UAAU,CAAC,IAAI,EAAE;QAC5B,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,aAAa,CAAC;CAgB3B"}