@semiont/make-meaning 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +28 -49
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -10,10 +10,10 @@
10
10
 
11
11
  This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHITECTURE.md). It owns the **Knowledge Base** and the actors that interface with it:
12
12
 
13
- - **Stower** (write) — the single write gateway to the Knowledge Base
14
- - **Gatherer** (read) — handles all browse reads, context assembly (passage + graph neighborhood + optional inference summary), and entity type listing
15
- - **Matcher** (search/link) — context-driven search with multi-source retrieval, composite structural scoring, optional LLM semantic scoring, and graph queries
16
- - **Browser** (filesystem reads) — merges live filesystem directory listings with KB metadata for tracked resources
13
+ - **Stower** (write) — the single write gateway to the Knowledge Base; handles all resource and annotation mutations and job lifecycle events
14
+ - **Browser** (read) — handles all KB read queries: resources, annotations, events, annotation history, referenced-by lookups, entity type listing, and directory browse (merging filesystem listings with KB metadata)
15
+ - **Gatherer** (context assembly) — assembles gathered context for annotations (`gather:requested`) and resources (`gather:resource-requested`)
16
+ - **Matcher** (search/link) — context-driven candidate search with multi-source retrieval, composite structural scoring, and optional LLM semantic scoring
17
17
  - **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
18
18
 
19
19
  All actors subscribe to the EventBus via RxJS pipelines. They expose only `initialize()` and `stop()` — no public business methods. Callers communicate with actors by putting events on the bus.
@@ -43,7 +43,7 @@ const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
43
43
 
44
44
  // Access components
45
45
  const { knowledgeSystem, jobQueue } = makeMeaning;
46
- const { kb, stower, gatherer, matcher, browser, cloneTokenManager } = knowledgeSystem;
46
+ const { kb, stower, browser, gatherer, matcher, cloneTokenManager } = knowledgeSystem;
47
47
 
48
48
  // Graceful shutdown
49
49
  await makeMeaning.stop();
@@ -51,42 +51,21 @@ await makeMeaning.stop();
51
51
 
52
52
  This single call initializes:
53
53
  - **KnowledgeSystem** — groups the Knowledge Base and its actors
54
- - **KnowledgeBase** — groups EventStore, ViewStorage, ContentStore, GraphDatabase, and GraphDBConsumer
54
+ - **KnowledgeBase** — groups EventStore, ViewStorage, WorkingTreeStore, GraphDatabase, and GraphDBConsumer
55
55
  - **Stower** — subscribes to write commands on EventBus
56
- - **Gatherer** — subscribes to browse reads, gather context, and entity type listing on EventBus
57
- - **Matcher** — subscribes to search and referenced-by queries on EventBus
58
- - **Browser** — subscribes to directory browse requests, merging filesystem + KB metadata
56
+ - **Browser** — subscribes to all KB read queries and directory browse requests on EventBus
57
+ - **Gatherer** — subscribes to annotation and resource gather requests on EventBus
58
+ - **Matcher** — subscribes to candidate search requests on EventBus
59
59
  - **CloneTokenManager** — subscribes to clone token operations on EventBus
60
60
  - **JobQueue** — background job processing queue + job status subscription
61
61
  - **6 annotation workers** — poll job queue for async AI tasks
62
62
 
63
- ### Create a Resource (via EventBus)
64
-
65
- ```typescript
66
- import { ResourceOperations } from '@semiont/make-meaning';
67
- import { userId } from '@semiont/core';
68
-
69
- const result = await ResourceOperations.createResource(
70
- {
71
- name: 'My Document',
72
- content: Buffer.from('Document content here'),
73
- format: 'text/plain',
74
- language: 'en',
75
- },
76
- userId('user-123'),
77
- eventBus,
78
- config.services.backend.publicURL,
79
- );
80
- ```
81
-
82
- `ResourceOperations.createResource` emits `yield:create` on the EventBus. The Stower subscribes to this event, persists the resource to the EventStore and ContentStore, and emits `yield:created` back on the bus.
83
-
84
63
  ### Gather Context (via EventBus)
85
64
 
86
65
  ```typescript
87
66
  import { firstValueFrom, race, filter, timeout } from 'rxjs';
88
67
 
89
- // Emit gather request
68
+ // Emit gather request for an annotation
90
69
  eventBus.get('gather:requested').next({
91
70
  annotationUri,
92
71
  resourceId,
@@ -116,29 +95,29 @@ graph TB
116
95
 
117
96
  subgraph ks ["Knowledge System"]
118
97
  STOWER["Stower<br/>(write)"]
119
- GATHERER["Gatherer<br/>(read)"]
98
+ BROWSER["Browser<br/>(read)"]
99
+ GATHERER["Gatherer<br/>(context assembly)"]
120
100
  MATCHER["Matcher<br/>(search/link)"]
121
- BROWSER["Browser<br/>(filesystem)"]
122
101
  CTM["CloneTokenManager<br/>(clone)"]
123
102
  KB["Knowledge Base"]
124
103
  STOWER -->|persist| KB
104
+ BROWSER -->|query| KB
125
105
  GATHERER -->|query| KB
126
106
  MATCHER -->|query| KB
127
- BROWSER -->|query| KB
128
107
  CTM -->|query| KB
129
108
  end
130
109
 
131
- BUS -->|"yield:create, mark:create,<br/>mark:delete, job:*"| STOWER
132
- BUS -->|"browse:*, gather:*,<br/>mark:entity-types-*"| GATHERER
133
- BUS -->|"bind:search-*,<br/>bind:referenced-by-*"| MATCHER
134
- BUS -->|"browse:directory-*"| BROWSER
135
- BUS -->|"yield:clone-*"| CTM
110
+ 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
111
+ 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
112
+ BUS -->|"gather:requested<br/>gather:resource-requested"| GATHERER
113
+ BUS -->|"match:search-requested"| MATCHER
114
+ BUS -->|"yield:clone-token-requested<br/>yield:clone-resource-requested<br/>yield:clone-create"| CTM
136
115
 
137
- STOWER -->|"yield:created, mark:created"| BUS
138
- GATHERER -->|"browse:*-result,<br/>gather:complete"| BUS
139
- MATCHER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
140
- BROWSER -->|"browse:directory-result"| BUS
141
- CTM -->|"yield:clone-token-generated,<br/>yield:clone-resource-result"| BUS
116
+ STOWER -->|"yield:created, yield:updated, yield:moved<br/>mark:created, mark:deleted, mark:body-updated<br/>mark:entity-type-added, ..."| BUS
117
+ 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
118
+ GATHERER -->|"gather:complete, gather:failed<br/>gather:resource-complete, gather:resource-failed"| BUS
119
+ MATCHER -->|"match:search-results, match:search-failed"| BUS
120
+ CTM -->|"yield:clone-token-generated<br/>yield:clone-resource-result<br/>yield:clone-created"| BUS
142
121
 
143
122
  classDef bus fill:#e8a838,stroke:#b07818,stroke-width:3px,color:#000,font-weight:bold
144
123
  classDef actor fill:#5a9a6a,stroke:#3d6644,stroke-width:2px,color:#fff
@@ -146,7 +125,7 @@ graph TB
146
125
  classDef caller fill:#4a90a4,stroke:#2c5f7a,stroke-width:2px,color:#fff
147
126
 
148
127
  class BUS bus
149
- class STOWER,GATHERER,MATCHER,BROWSER,CTM actor
128
+ class STOWER,BROWSER,GATHERER,MATCHER,CTM actor
150
129
  class KB kb
151
130
  class Routes,Workers,EBC caller
152
131
  ```
@@ -161,7 +140,7 @@ The **Knowledge Base** is an inert store — it has no intelligence, no goals, n
161
140
  |-------|---------------|---------|
162
141
  | **Event Log** | `EventStore` | Immutable append-only log of all domain events |
163
142
  | **Materialized Views** | `ViewStorage` | Denormalized projections for fast reads |
164
- | **Content Store** | `WorkingTreeStore` | Content-addressed binary storage (SHA-256) |
143
+ | **Content Store** | `WorkingTreeStore` | Working-tree files addressed by URI |
165
144
  | **Graph** | `GraphDatabase` | Eventually consistent relationship projection |
166
145
  | **Graph Consumer** | `GraphDBConsumer` | Event-to-graph synchronization pipeline |
167
146
 
@@ -204,9 +183,9 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
204
183
  ### Actors
205
184
 
206
185
  - `Stower` — Write gateway actor
207
- - `Gatherer` — Read actor (browse reads, context assembly, entity type listing)
208
- - `Matcher` — Search/link actor (context-driven search, entity resolution, referenced-by queries)
209
- - `Browser` — Filesystem read actor (directory listings merged with KB metadata)
186
+ - `Browser` — Read actor (all KB queries, directory listings merged with KB metadata)
187
+ - `Gatherer` — Context assembly actor (annotation and resource gather flows)
188
+ - `Matcher` — Search/link actor (context-driven candidate search with structural + semantic scoring)
210
189
  - `CloneTokenManager` — Clone token lifecycle actor (yield domain)
211
190
 
212
191
  ### Operations
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@semiont/make-meaning",
3
- "version": "0.4.4",
3
+ "version": "0.4.6",
4
4
  "type": "module",
5
5
  "description": "Making meaning from resources through context assembly, pattern detection, and relationship reasoning",
6
6
  "main": "./dist/index.js",