@semiont/sdk 0.5.2 → 0.5.3

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/index.d.ts

@@ -2,8 +2,8 @@ import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject, Subject } from 'rxjs';
 export { firstValueFrom, lastValueFrom } from 'rxjs';
 import * as _semiont_core from '@semiont/core';
-import { ResourceId, components, UserDID, paths, BackendDownload, ProgressEvent, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, 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, UserId, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } 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';
 
 /**
@@ -203,6 +203,8 @@ interface GenerationOptions {
     storageUri: string;
     context: GatheredContext;
     prompt?: string;
+    /** Entity-type tags to stamp on the synthesized resource. Used both as a prompt bias for the generation worker and as the `entityTypes` set on the resulting resource (so `browse.resources({ entityType: ... })` queries can find it). */
+    entityTypes?: string[];
     /** Annotation/resource body locale — language the generated resource is written in (typically the user's UI locale). */
     language?: string;
     /** Source-resource locale — language of the resource the annotation lives on, used in the prompt so the LLM understands embedded source-context snippets. BCP-47. */
@@ -297,6 +299,7 @@ interface BrowseNamespace$1 {
     annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
     annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
     entityTypes(): CacheObservable<string[]>;
+    tagSchemas(): CacheObservable<TagSchema[]>;
     referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
     events(resourceId: ResourceId): CacheObservable<StoredEventResponse$1[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
@@ -346,6 +349,16 @@ interface FrameNamespace$1 {
     addEntityType(type: string): Promise<void>;
     /** Add multiple entity types in one call. Convenience over a loop of `addEntityType`. */
     addEntityTypes(types: string[]): Promise<void>;
+    /**
+     * Register a tag schema with the KB's runtime registry.
+     *
+     * Most-recent registration of a given `schema.id` wins; identical
+     * re-registrations are silent, differing content overwrites the
+     * existing entry and logs a warning. KBs typically call this at
+     * session/skill startup so the schema is available for `mark.assist`
+     * with motivation `tagging` and surfaces in `browse.tagSchemas()`.
+     */
+    addTagSchema(schema: TagSchema): Promise<void>;
 }
 /**
  * Mark — annotation CRUD, AI assist, resource lifecycle
@@ -551,6 +564,7 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
     private readonly annotationDetailCache;
     private readonly annotationResources;
     private readonly entityTypesCache;
+    private readonly tagSchemasCache;
     private readonly referencedByCache;
     private readonly resourceEventsCache;
     /** Filter-blob memory so `invalidateResourceLists` can replay per-key. */
@@ -571,6 +585,7 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
     annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
     annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
     entityTypes(): CacheObservable<string[]>;
+    tagSchemas(): CacheObservable<TagSchema[]>;
     referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
     events(resourceId: ResourceId): CacheObservable<StoredEventResponse[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
@@ -599,6 +614,7 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
     invalidateResourceDetail(id: ResourceId): void;
     invalidateResourceLists(): void;
     invalidateEntityTypes(): void;
+    invalidateTagSchemas(): void;
     invalidateReferencedBy(resourceId: ResourceId): void;
     invalidateResourceEvents(resourceId: ResourceId): void;
     updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation): void;
@@ -737,6 +753,7 @@ declare class FrameNamespace implements FrameNamespace$1 {
     constructor(transport: ITransport);
     addEntityType(type: string): Promise<void>;
     addEntityTypes(types: string[]): Promise<void>;
+    addTagSchema(schema: TagSchema): Promise<void>;
 }
 
 type JobStatusResponse = components['schemas']['JobStatusResponse'];

package/dist/index.js

@@ -171,6 +171,7 @@ function createCache(fetchFn) {
 
 // src/namespaces/browse.ts
 var ENTITY_TYPES_KEY = "_";
+var TAG_SCHEMAS_KEY = "_";
 var BrowseNamespace = class {
   constructor(transport, bus, content) {
     this.transport = transport;
@@ -231,6 +232,16 @@ var BrowseNamespace = class {
       );
       return result.entityTypes;
     });
+    this.tagSchemasCache = createCache(async () => {
+      const result = await busRequest(
+        this.transport,
+        "browse:tag-schemas-requested",
+        {},
+        "browse:tag-schemas-result",
+        "browse:tag-schemas-failed"
+      );
+      return result.tagSchemas;
+    });
     this.referencedByCache = createCache(async (resourceId2) => {
       const result = await busRequest(
         this.transport,
@@ -274,6 +285,7 @@ var BrowseNamespace = class {
   annotationDetailCache;
   annotationResources = /* @__PURE__ */ new Map();
   entityTypesCache;
+  tagSchemasCache;
   referencedByCache;
   resourceEventsCache;
   /** Filter-blob memory so `invalidateResourceLists` can replay per-key. */
@@ -316,6 +328,9 @@ var BrowseNamespace = class {
   entityTypes() {
     return CacheObservable.from(this.entityTypesCache.observe(ENTITY_TYPES_KEY));
   }
+  tagSchemas() {
+    return CacheObservable.from(this.tagSchemasCache.observe(TAG_SCHEMAS_KEY));
+  }
   referencedBy(resourceId2) {
     return CacheObservable.from(this.referencedByCache.observe(resourceId2));
   }
@@ -400,6 +415,9 @@ var BrowseNamespace = class {
   invalidateEntityTypes() {
     this.entityTypesCache.invalidate(ENTITY_TYPES_KEY);
   }
+  invalidateTagSchemas() {
+    this.tagSchemasCache.invalidate(TAG_SCHEMAS_KEY);
+  }
   invalidateReferencedBy(resourceId2) {
     this.referencedByCache.invalidate(resourceId2);
   }
@@ -476,6 +494,7 @@ var BrowseNamespace = class {
         for (const rId of this.referencedByCache.keys()) this.invalidateReferencedBy(rId);
       }
       this.invalidateEntityTypes();
+      this.invalidateTagSchemas();
     });
     this.on("mark:delete-ok", (event) => {
       this.removeAnnotationDetail(annotationId(event.annotationId));
@@ -511,6 +530,7 @@ var BrowseNamespace = class {
     this.on("mark:archived", this.onArchiveToggled);
     this.on("mark:unarchived", this.onArchiveToggled);
     this.on("frame:entity-type-added", () => this.invalidateEntityTypes());
+    this.on("frame:tag-schema-added", () => this.invalidateTagSchemas());
   }
 };
 var MarkNamespace = class {
@@ -543,6 +563,7 @@ var MarkNamespace = class {
       let done = false;
       let pollTimer = null;
       let pollInterval = null;
+      let unsubscribeResource = this.transport.subscribeToResource(resourceId2);
       const cleanup = () => {
         done = true;
         if (pollTimer) {
@@ -553,6 +574,10 @@ var MarkNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
+        if (unsubscribeResource) {
+          unsubscribeResource();
+          unsubscribeResource = null;
+        }
       };
       const resetPollTimer = (jobId) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -867,6 +892,7 @@ var YieldNamespace = class {
       let done = false;
       let pollTimer = null;
       let pollInterval = null;
+      let unsubscribeResource = this.transport.subscribeToResource(resourceId2);
       const cleanup = () => {
         done = true;
         if (pollTimer) {
@@ -877,6 +903,10 @@ var YieldNamespace = class {
           clearInterval(pollInterval);
           pollInterval = null;
         }
+        if (unsubscribeResource) {
+          unsubscribeResource();
+          unsubscribeResource = null;
+        }
       };
       const resetPollTimer = (jid) => {
         if (pollTimer) clearTimeout(pollTimer);
@@ -950,6 +980,7 @@ var YieldNamespace = class {
             referenceId: annotationId2,
             title: options.title,
             prompt: options.prompt,
+            entityTypes: options.entityTypes,
             language: options.language,
             sourceLanguage: options.sourceLanguage,
             temperature: options.temperature,
@@ -1041,6 +1072,9 @@ var FrameNamespace = class {
       await this.transport.emit("frame:add-entity-type", { tag });
     }
   }
+  async addTagSchema(schema) {
+    await this.transport.emit("frame:add-tag-schema", { schema });
+  }
 };
 
 // src/namespaces/job.ts