@semiont/make-meaning 0.5.1 → 0.5.3

package/README.md

@@ -115,14 +115,14 @@ graph TB
         CTM -->|query| KB
     end
 
-    BUS -->|"yield:create, yield:update, yield:mv<br/>mark:create, mark:delete, mark:update-body<br/>mark:add-entity-type, mark:archive, mark:unarchive<br/>mark:update-entity-types, job:start, job:*"| STOWER
+    BUS -->|"yield:create, yield:update, yield:mv<br/>mark:create, mark:delete, mark:update-body<br/>frame:add-entity-type, mark:archive, mark:unarchive<br/>mark:update-entity-types, job:start, job:*"| STOWER
     BUS -->|"browse:resource-requested, browse:resources-requested<br/>browse:annotations-requested, browse:annotation-requested<br/>browse:events-requested, browse:annotation-history-requested<br/>browse:referenced-by-requested, browse:entity-types-requested<br/>browse:directory-requested"| BROWSER
     BUS -->|"gather:requested<br/>gather:resource-requested"| GATHERER
     BUS -->|"match:search-requested"| MATCHER
     BUS -->|"yield:created, mark:created,<br/>mark:body-updated"| SMELTER
     BUS -->|"yield:clone-token-requested<br/>yield:clone-resource-requested<br/>yield:clone-create"| CTM
 
-    STOWER -->|"yield:created, yield:updated, yield:moved<br/>mark:created, mark:deleted, mark:body-updated<br/>mark:entity-type-added, ..."| BUS
+    STOWER -->|"yield:created, yield:updated, yield:moved<br/>mark:created, mark:deleted, mark:body-updated<br/>frame:entity-type-added, ..."| BUS
     BROWSER -->|"browse:resource-result, browse:resources-result<br/>browse:annotations-result, browse:annotation-result<br/>browse:events-result, browse:annotation-history-result<br/>browse:referenced-by-result, browse:entity-types-result<br/>browse:directory-result"| BUS
     GATHERER -->|"gather:complete, gather:failed<br/>gather:resource-complete, gather:resource-failed"| BUS
     MATCHER -->|"match:search-results, match:search-failed"| BUS
@@ -170,6 +170,19 @@ const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
 
 The EventBus is created by the backend (or script) and passed into `startMakeMeaning()` as a dependency. Make-meaning does not own or encapsulate the EventBus — it is shared across the entire system.
 
+### Pure projection validators
+
+The dispatcher in [`src/handlers/job-commands.ts`](src/handlers/job-commands.ts) does projection-validated job creation: when a `mark.assist` (linking) or `yield.fromAnnotation` job arrives with `entityTypes`, the dispatcher validates that every tag is registered; when a tagging job arrives with a `schemaId`, the dispatcher resolves it against the registered tag-schema set.
+
+Both rules are pure functions in [`src/views/projection-validators.ts`](src/views/projection-validators.ts):
+
+- `resolveTagSchema(schemas, schemaId)` → `{ schema } | { error }` — id lookup with the standard "Tag schema not registered" / "tag-annotation requires schemaId" error formats.
+- `validateEntityTypes(registered, requested)` → `{ ok: true } | { ok: false; unknown }` — set membership check that lists the offending tags in caller order.
+
+The dispatcher is the I/O shell: read the projection (via the readers in `src/views/`), pass it to the validator (pure), then either stash the resolved value or rethrow as `job:create-failed`. Validator unit tests run in single-digit milliseconds with no filesystem, no event-bus, no mock JobQueue — the dispatcher integration tests in `__tests__/handlers/job-commands.test.ts` keep the wiring covered.
+
+This pattern (functional core, imperative shell) is shared with `@semiont/event-sourcing`'s projection reducers; see [`docs/system/PROJECTION-PATTERN.md`](../../docs/system/PROJECTION-PATTERN.md) for the architectural narrative, the full axiom catalog, and guidance for adding new validators.
+
 ## Documentation
 
 - **[Architecture](./docs/architecture.md)** — Actor model, data flow, storage architecture

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { JobQueue } from '@semiont/jobs';
 import { SemiontProject } from '@semiont/core/node';
-import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, UserDID, EventMap, Email, GoogleCredential, RefreshToken, UserResponse, ListUsersResponse, UpdateUserRequest, UpdateUserResponse, ProgressCallback, ProgressEvent, HealthCheckResponse, StatusResponse, IContentTransport, PutBinaryRequest, AccessToken, ContentFormat as ContentFormat$1, Annotation, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, ContentFormat as ContentFormat$1, AccessToken, Annotation, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
 export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
 import { EventStore, ViewStorage } from '@semiont/event-sourcing';
 import { WorkingTreeStore } from '@semiont/content';
@@ -8,6 +8,7 @@ import { GraphDatabase } from '@semiont/graph';
 import { VectorStore, EmbeddingProvider } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
 import { BehaviorSubject, Observable } from 'rxjs';
+import { StateUnit, WorkerBus } from '@semiont/sdk';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -170,8 +171,8 @@ declare class GraphDBConsumer {
  * - Vectors (semantic search) — via VectorStore (optional, read-only)
  *
  * The Smelter (event-to-vector projection) runs as an external actor
- * via @semiont/jobs/smelter-main. It subscribes to domain events via
- * the EventBus gateway, embeds content, and writes to Qdrant directly.
+ * via @semiont/make-meaning/smelter-main. It subscribes to domain events
+ * via the EventBus gateway, embeds content, and writes to Qdrant directly.
  */
 
 interface KnowledgeBase {
@@ -213,7 +214,8 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * - mark:update-body   → annotation.body.updated              → (no result event yet)
  * - mark:archive       → resource.archived (+ file removal)   (resource-scoped, no result event)
  * - mark:unarchive     → resource.unarchived                  (resource-scoped, no result event)
- * - mark:add-entity-type → entitytype.added                   → mark:entity-type-added / mark:entity-type-add-failed
+ * - frame:add-entity-type → entitytype.added                   → frame:entity-type-added / frame:entity-type-add-failed
+ * - frame:add-tag-schema  → tagschema.added                    → frame:tag-schema-added / frame:tag-schema-add-failed
  * - mark:update-entity-types → entitytag.added / entitytag.removed
  * - job:start          → job.started
  * - job:complete       → job.completed
@@ -246,6 +248,7 @@ declare class Stower {
     private handleMarkArchive;
     private handleMarkUnarchive;
     private handleAddEntityType;
+    private handleAddTagSchema;
     private handleUpdateEntityTypes;
     private handleJobStart;
     private handleJobComplete;
@@ -365,6 +368,7 @@ declare class Matcher {
  * - browse:annotation-history-requested — annotation event history
  * - browse:referenced-by-requested — find annotations in the KB graph that reference a resource
  * - browse:entity-types-requested — list entity types from the project projection
+ * - browse:tag-schemas-requested — list tag schemas from the project projection
  * - browse:directory-requested — list a project directory, merging fs + ViewStorage
  */
 
@@ -385,6 +389,7 @@ declare class Browser {
     private handleBrowseAnnotationHistory;
     private handleReferencedBy;
     private handleEntityTypes;
+    private handleTagSchemas;
     private handleBrowseDirectory;
     stop(): Promise<void>;
 }
@@ -474,15 +479,13 @@ declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningCo
  *     and forwards each onto `clientBus`.
  *   - The bus reference flows client → transport, never the other way.
  *
- * Auth, admin, and exchange methods are not implemented in Phase 2 — local
- * mode runs as a single host-process identity supplied at construction.
- * Calling them throws.
+ * LocalTransport implements `ITransport` only. Auth, admin, and exchange
+ * (`IBackendOperations`) are HTTP-shaped concepts that don't apply
+ * in-process — local mode runs as a single host-process identity supplied
+ * at construction, with no token/credential lifecycle. A `SemiontClient`
+ * built over this transport has no `.auth` / `.admin` namespaces.
  */
 
-type AuthResponse = components['schemas']['AuthResponse'];
-type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
-type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
-type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
 interface LocalTransportConfig {
     /**
      * The in-process knowledge system. Lifetime is owned by the caller —
@@ -512,6 +515,18 @@ interface LocalTransportConfig {
 declare class LocalTransport implements ITransport {
     readonly baseUrl: BaseUrl;
     readonly state$: BehaviorSubject<ConnectionState>;
+    private readonly errorsSubject;
+    /**
+     * Stream of `SemiontError` instances surfaced from transport-mediated
+     * round-trips (typed-wire methods on this transport that fail). The
+     * in-process implementation does not currently surface errors through
+     * this stream — most failures here originate inside the make-meaning
+     * actors and surface through bus channels (correlation-ID failures via
+     * `busRequest`). The Subject exists to satisfy the `ITransport`
+     * contract; future expansion (e.g. transport-level guard failures)
+     * can publish into it.
+     */
+    readonly errors$: Observable<SemiontError>;
     private readonly bus;
     private readonly userId;
     private readonly bridges;
@@ -523,30 +538,6 @@ declare class LocalTransport implements ITransport {
     stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
     subscribeToResource(_resourceId: ResourceId): () => void;
     bridgeInto(bus: EventBus): void;
-    authenticatePassword(_email: Email, _password: string): Promise<AuthResponse>;
-    authenticateGoogle(_credential: GoogleCredential): Promise<AuthResponse>;
-    refreshAccessToken(_token: RefreshToken): Promise<TokenRefreshResponse>;
-    logout(): Promise<void>;
-    acceptTerms(): Promise<void>;
-    getCurrentUser(): Promise<UserResponse>;
-    generateMcpToken(): Promise<{
-        token: string;
-    }>;
-    getMediaToken(_resourceId: ResourceId): Promise<{
-        token: string;
-    }>;
-    listUsers(): Promise<ListUsersResponse>;
-    getUserStats(): Promise<AdminUserStatsResponse>;
-    updateUser(_id: UserDID, _data: UpdateUserRequest): Promise<UpdateUserResponse>;
-    getOAuthConfig(): Promise<OAuthConfigResponse>;
-    backupKnowledgeBase(): Promise<Response>;
-    restoreKnowledgeBase(_file: File, _onProgress?: ProgressCallback): Promise<ProgressEvent>;
-    exportKnowledgeBase(_params?: {
-        includeArchived?: boolean;
-    }): Promise<Response>;
-    importKnowledgeBase(_file: File, _onProgress?: ProgressCallback): Promise<ProgressEvent>;
-    healthCheck(): Promise<HealthCheckResponse>;
-    getStatus(): Promise<StatusResponse>;
     dispose(): void;
 }
 
@@ -568,9 +559,7 @@ declare class LocalTransport implements ITransport {
 declare class LocalContentTransport implements IContentTransport {
     private readonly ks;
     constructor(ks: KnowledgeSystem);
-    putBinary(_request: PutBinaryRequest, _options?: {
-        auth?: AccessToken;
-    }): Promise<{
+    putBinary(_request: PutBinaryRequest, _options?: PutBinaryOptions): Promise<{
         resourceId: ResourceId;
     }>;
     getBinary(resourceId: ResourceId, options?: {
@@ -632,7 +621,7 @@ declare function registerAnnotationLookupHandlers(eventBus: EventBus, kb: Knowle
  */
 declare function registerBindUpdateBodyHandler(eventBus: EventBus, parentLogger: Logger): void;
 
-declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, parentLogger: Logger): void;
+declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, project: SemiontProject, parentLogger: Logger): void;
 
 /**
  * Bus command handlers — pure bus-event translators that bridge the
@@ -651,13 +640,13 @@ declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQue
  * Register all bus command handlers on the make-meaning EventBus. Called
  * during `startMakeMeaning` after the JobQueue and KnowledgeSystem exist.
  */
-declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: KnowledgeSystem, jobQueue: JobQueue, logger: Logger): void;
+declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: KnowledgeSystem, jobQueue: JobQueue, project: SemiontProject, logger: Logger): void;
 
 /**
  * Entity Types Bootstrap
  *
  * On startup, seeds the KB with DEFAULT_ENTITY_TYPES by emitting
- * mark:add-entity-type for each missing type. Reads the __system__ event
+ * frame:add-entity-type for each missing type. Reads the __system__ event
  * stream (the durable source of truth in .semiont/events/) to determine
  * which types already exist.
  *
@@ -673,7 +662,7 @@ declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: Knowle
 
 /**
  * Bootstrap entity types if any are missing from the event log.
- * Reads the __system__ stream to find existing mark:entity-type-added events,
+ * Reads the __system__ stream to find existing frame:entity-type-added events,
  * then emits only the missing ones.
  */
 declare function bootstrapEntityTypes(eventBus: EventBus, eventStore: EventStore, logger?: Logger): Promise<void>;
@@ -690,6 +679,36 @@ declare function bootstrapEntityTypes(eventBus: EventBus, eventStore: EventStore
  */
 declare function readEntityTypesProjection(project: SemiontProject): Promise<string[]>;
 
+/**
+ * SmelterActorStateUnit — domain-event fan-in for the Smelter worker.
+ *
+ * Subscribes to the six smelter-relevant channels on a shared bus and
+ * exposes them as a single typed `events$` stream. Transport-neutral —
+ * the caller passes a `WorkerBus` (HTTP `ActorStateUnit` today, an in-process
+ * bus shim if/when one exists). The state unit does not own the bus and does
+ * not dispose it.
+ *
+ * `start()` widens the bus's channel-subscription set to include the
+ * smelter channels. On HTTP this extends the SSE subscription URL;
+ * on an in-process bus this is a no-op (the underlying `EventBus`
+ * already delivers every emit).
+ */
+
+interface SmelterEvent {
+    type: string;
+    resourceId?: string;
+    payload: Record<string, unknown>;
+}
+interface SmelterActorStateUnitOptions {
+    bus: WorkerBus;
+}
+interface SmelterActorStateUnit extends StateUnit {
+    events$: Observable<SmelterEvent>;
+    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
+    start(): void;
+}
+declare function createSmelterActorStateUnit(options: SmelterActorStateUnitOptions): SmelterActorStateUnit;
+
 /**
  * Exchange Format Manifest Types
  *
@@ -901,7 +920,7 @@ interface LinkedDataImportResult {
  *   1. Stream and decompress tar.gz entries
  *   2. Parse .semiont/manifest.jsonld → validate format
  *   3. Build blob resolver over root-level content entries
- *   4. Add entity types from manifest via mark:add-entity-type
+ *   4. Add entity types from manifest via frame:add-entity-type
  *   5. For each .semiont/resources/{id}.jsonld:
  *      a. Parse JSON-LD document
  *      b. Resolve content blob by checksum from representations
@@ -1222,4 +1241,4 @@ declare function generateReferenceSuggestions(referenceTitle: string, client: In
 declare const PACKAGE_NAME = "@semiont/make-meaning";
 declare const VERSION = "0.1.0";
 
-export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, type BackupContentReader, type BackupEventStoreReader, type BackupExporterOptions, type BackupImportResult, type BackupImporterOptions, type BackupManifestHeader, type BackupStreamSummary, Browser, type BuildContextOptions, CloneTokenManager, type ContentBlobResolver, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, type GraphEdge, type GraphNode, type GraphRepresentation, type KnowledgeBase, type KnowledgeSystem, LLMContext, type LLMContextOptions, type LinkedDataContentReader, type LinkedDataExporterOptions, type LinkedDataImportResult, type LinkedDataImporterOptions, type LinkedDataViewReader, type ListResourcesFilters, LocalContentTransport, LocalTransport, type LocalTransportConfig, type MakeMeaningConfig, type MakeMeaningService, Matcher, PACKAGE_NAME, type ReplayStats, ResourceContext, ResourceOperations, Stower, type UpdateAnnotationBodyResult, VERSION, bootstrapEntityTypes, createKnowledgeBase, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
+export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, type BackupContentReader, type BackupEventStoreReader, type BackupExporterOptions, type BackupImportResult, type BackupImporterOptions, type BackupManifestHeader, type BackupStreamSummary, Browser, type BuildContextOptions, CloneTokenManager, type ContentBlobResolver, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, type GraphEdge, type GraphNode, type GraphRepresentation, type KnowledgeBase, type KnowledgeSystem, LLMContext, type LLMContextOptions, type LinkedDataContentReader, type LinkedDataExporterOptions, type LinkedDataImportResult, type LinkedDataImporterOptions, type LinkedDataViewReader, type ListResourcesFilters, LocalContentTransport, LocalTransport, type LocalTransportConfig, type MakeMeaningConfig, type MakeMeaningService, Matcher, PACKAGE_NAME, type ReplayStats, ResourceContext, ResourceOperations, type SmelterActorStateUnit, type SmelterActorStateUnitOptions, type SmelterEvent, Stower, type UpdateAnnotationBodyResult, VERSION, bootstrapEntityTypes, createKnowledgeBase, createSmelterActorStateUnit, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };