@semiont/make-meaning 0.4.2 → 0.4.4
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.
- package/README.md +54 -33
- package/dist/index.d.ts +147 -117
- package/dist/index.js +959 -857
- package/dist/index.js.map +1 -1
- package/package.json +3 -5
package/README.md
CHANGED
|
@@ -13,6 +13,7 @@ This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHIT
|
|
|
13
13
|
- **Stower** (write) — the single write gateway to the Knowledge Base
|
|
14
14
|
- **Gatherer** (read) — handles all browse reads, context assembly (passage + graph neighborhood + optional inference summary), and entity type listing
|
|
15
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
|
|
16
17
|
- **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
|
|
17
18
|
|
|
18
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.
|
|
@@ -29,29 +30,33 @@ npm install @semiont/make-meaning
|
|
|
29
30
|
|
|
30
31
|
```typescript
|
|
31
32
|
import { startMakeMeaning } from '@semiont/make-meaning';
|
|
33
|
+
import { SemiontProject } from '@semiont/core/node';
|
|
32
34
|
import { EventBus } from '@semiont/core';
|
|
33
|
-
import type {
|
|
35
|
+
import type { Logger } from '@semiont/core';
|
|
34
36
|
|
|
35
37
|
// EventBus is created outside make-meaning — it is not encapsulated by this package
|
|
36
38
|
const eventBus = new EventBus();
|
|
39
|
+
const project = new SemiontProject('/path/to/project');
|
|
37
40
|
|
|
38
41
|
// Start all infrastructure
|
|
39
|
-
const makeMeaning = await startMakeMeaning(config, eventBus, logger);
|
|
42
|
+
const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
|
|
40
43
|
|
|
41
44
|
// Access components
|
|
42
|
-
const {
|
|
45
|
+
const { knowledgeSystem, jobQueue } = makeMeaning;
|
|
46
|
+
const { kb, stower, gatherer, matcher, browser, cloneTokenManager } = knowledgeSystem;
|
|
43
47
|
|
|
44
48
|
// Graceful shutdown
|
|
45
49
|
await makeMeaning.stop();
|
|
46
50
|
```
|
|
47
51
|
|
|
48
52
|
This single call initializes:
|
|
49
|
-
- **
|
|
50
|
-
- **
|
|
51
|
-
- **
|
|
52
|
-
- **
|
|
53
|
-
- **
|
|
54
|
-
- **
|
|
53
|
+
- **KnowledgeSystem** — groups the Knowledge Base and its actors
|
|
54
|
+
- **KnowledgeBase** — groups EventStore, ViewStorage, ContentStore, GraphDatabase, and GraphDBConsumer
|
|
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
|
|
59
|
+
- **CloneTokenManager** — subscribes to clone token operations on EventBus
|
|
55
60
|
- **JobQueue** — background job processing queue + job status subscription
|
|
56
61
|
- **6 annotation workers** — poll job queue for async AI tasks
|
|
57
62
|
|
|
@@ -101,7 +106,7 @@ const result = await firstValueFrom(
|
|
|
101
106
|
|
|
102
107
|
### Actor Model
|
|
103
108
|
|
|
104
|
-
All meaningful actions flow through the EventBus. The
|
|
109
|
+
All meaningful actions flow through the EventBus. The KB actors are reactive — they subscribe via RxJS pipelines in `initialize()` and communicate results by emitting on the bus.
|
|
105
110
|
|
|
106
111
|
```mermaid
|
|
107
112
|
graph TB
|
|
@@ -109,19 +114,30 @@ graph TB
|
|
|
109
114
|
Workers["Job Workers"] -->|commands| BUS
|
|
110
115
|
EBC["EventBusClient"] -->|commands| BUS
|
|
111
116
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
117
|
+
subgraph ks ["Knowledge System"]
|
|
118
|
+
STOWER["Stower<br/>(write)"]
|
|
119
|
+
GATHERER["Gatherer<br/>(read)"]
|
|
120
|
+
MATCHER["Matcher<br/>(search/link)"]
|
|
121
|
+
BROWSER["Browser<br/>(filesystem)"]
|
|
122
|
+
CTM["CloneTokenManager<br/>(clone)"]
|
|
123
|
+
KB["Knowledge Base"]
|
|
124
|
+
STOWER -->|persist| KB
|
|
125
|
+
GATHERER -->|query| KB
|
|
126
|
+
MATCHER -->|query| KB
|
|
127
|
+
BROWSER -->|query| KB
|
|
128
|
+
CTM -->|query| KB
|
|
129
|
+
end
|
|
130
|
+
|
|
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
|
|
121
136
|
|
|
122
137
|
STOWER -->|"yield:created, mark:created"| BUS
|
|
123
138
|
GATHERER -->|"browse:*-result,<br/>gather:complete"| BUS
|
|
124
139
|
MATCHER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
|
|
140
|
+
BROWSER -->|"browse:directory-result"| BUS
|
|
125
141
|
CTM -->|"yield:clone-token-generated,<br/>yield:clone-resource-result"| BUS
|
|
126
142
|
|
|
127
143
|
classDef bus fill:#e8a838,stroke:#b07818,stroke-width:3px,color:#000,font-weight:bold
|
|
@@ -130,27 +146,30 @@ graph TB
|
|
|
130
146
|
classDef caller fill:#4a90a4,stroke:#2c5f7a,stroke-width:2px,color:#fff
|
|
131
147
|
|
|
132
148
|
class BUS bus
|
|
133
|
-
class STOWER,GATHERER,MATCHER,CTM actor
|
|
149
|
+
class STOWER,GATHERER,MATCHER,BROWSER,CTM actor
|
|
134
150
|
class KB kb
|
|
135
151
|
class Routes,Workers,EBC caller
|
|
136
152
|
```
|
|
137
153
|
|
|
138
|
-
### Knowledge Base
|
|
154
|
+
### Knowledge System and Knowledge Base
|
|
139
155
|
|
|
140
|
-
The Knowledge
|
|
156
|
+
The **Knowledge System** binds the Knowledge Base to its actors. Nothing outside the Knowledge System reads or writes the Knowledge Base directly.
|
|
157
|
+
|
|
158
|
+
The **Knowledge Base** is an inert store — it has no intelligence, no goals, no decisions. It groups five subsystems:
|
|
141
159
|
|
|
142
160
|
| Store | Implementation | Purpose |
|
|
143
161
|
|-------|---------------|---------|
|
|
144
162
|
| **Event Log** | `EventStore` | Immutable append-only log of all domain events |
|
|
145
163
|
| **Materialized Views** | `ViewStorage` | Denormalized projections for fast reads |
|
|
146
|
-
| **Content Store** | `
|
|
164
|
+
| **Content Store** | `WorkingTreeStore` | Content-addressed binary storage (SHA-256) |
|
|
147
165
|
| **Graph** | `GraphDatabase` | Eventually consistent relationship projection |
|
|
166
|
+
| **Graph Consumer** | `GraphDBConsumer` | Event-to-graph synchronization pipeline |
|
|
148
167
|
|
|
149
168
|
```typescript
|
|
150
169
|
import { createKnowledgeBase } from '@semiont/make-meaning';
|
|
151
170
|
|
|
152
|
-
const kb = createKnowledgeBase(eventStore,
|
|
153
|
-
// kb.eventStore, kb.views, kb.content, kb.graph
|
|
171
|
+
const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
|
|
172
|
+
// kb.eventStore, kb.views, kb.content, kb.graph, kb.graphConsumer
|
|
154
173
|
```
|
|
155
174
|
|
|
156
175
|
### EventBus Ownership
|
|
@@ -169,19 +188,25 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
|
|
|
169
188
|
|
|
170
189
|
### Service (Primary)
|
|
171
190
|
|
|
172
|
-
- `startMakeMeaning(config, eventBus, logger)` — Initialize all infrastructure
|
|
173
|
-
- `MakeMeaningService` — Type for service return value
|
|
191
|
+
- `startMakeMeaning(project, config, eventBus, logger)` — Initialize all infrastructure
|
|
192
|
+
- `MakeMeaningService` — Type for service return value (`knowledgeSystem`, `jobQueue`, `workers`, `stop`)
|
|
193
|
+
|
|
194
|
+
### Knowledge System
|
|
195
|
+
|
|
196
|
+
- `KnowledgeSystem` — Interface grouping the Knowledge Base and its actors
|
|
197
|
+
- `stopKnowledgeSystem(ks)` — Ordered teardown of the Knowledge System
|
|
174
198
|
|
|
175
199
|
### Knowledge Base
|
|
176
200
|
|
|
177
|
-
- `createKnowledgeBase(
|
|
178
|
-
- `KnowledgeBase` — Interface grouping the
|
|
201
|
+
- `createKnowledgeBase(eventStore, project, graphDb, logger)` — Async factory function
|
|
202
|
+
- `KnowledgeBase` — Interface grouping the five KB stores (including `graphConsumer`)
|
|
179
203
|
|
|
180
204
|
### Actors
|
|
181
205
|
|
|
182
206
|
- `Stower` — Write gateway actor
|
|
183
207
|
- `Gatherer` — Read actor (browse reads, context assembly, entity type listing)
|
|
184
208
|
- `Matcher` — Search/link actor (context-driven search, entity resolution, referenced-by queries)
|
|
209
|
+
- `Browser` — Filesystem read actor (directory listings merged with KB metadata)
|
|
185
210
|
- `CloneTokenManager` — Clone token lifecycle actor (yield domain)
|
|
186
211
|
|
|
187
212
|
### Operations
|
|
@@ -201,10 +226,6 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
|
|
|
201
226
|
- `generateResourceSummary` — Resource summarization
|
|
202
227
|
- `generateReferenceSuggestions` — Smart suggestion generation
|
|
203
228
|
|
|
204
|
-
### Graph
|
|
205
|
-
|
|
206
|
-
- `GraphDBConsumer` — Event-to-graph synchronization
|
|
207
|
-
|
|
208
229
|
## Dependencies
|
|
209
230
|
|
|
210
231
|
- **[@semiont/core](../core/)** — Core types, EventBus, utilities
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { JobQueue, ReferenceAnnotationWorker, GenerationWorker, HighlightAnnotationWorker, AssessmentAnnotationWorker, CommentAnnotationWorker, TagAnnotationWorker } from '@semiont/jobs';
|
|
2
|
-
import { EventStore, ViewStorage } from '@semiont/event-sourcing';
|
|
3
2
|
import { SemiontProject } from '@semiont/core/node';
|
|
4
|
-
import { GraphServiceConfig, Logger, StoredEvent, ResourceId, EventBus,
|
|
3
|
+
import { GraphServiceConfig, Logger, StoredEvent, ResourceId, components, EventBus, AnnotationId, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
|
|
5
4
|
export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
|
|
6
|
-
import {
|
|
7
|
-
import { GraphDatabase } from '@semiont/graph';
|
|
5
|
+
import { EventStore, ViewStorage } from '@semiont/event-sourcing';
|
|
8
6
|
import { WorkingTreeStore } from '@semiont/content';
|
|
7
|
+
import { GraphDatabase } from '@semiont/graph';
|
|
8
|
+
import { InferenceClient } from '@semiont/inference';
|
|
9
9
|
import { Writable, Readable } from 'node:stream';
|
|
10
10
|
|
|
11
11
|
/**
|
|
@@ -146,13 +146,14 @@ declare class GraphDBConsumer {
|
|
|
146
146
|
/**
|
|
147
147
|
* Knowledge Base
|
|
148
148
|
*
|
|
149
|
-
* The
|
|
150
|
-
* Groups the
|
|
149
|
+
* The durable store that records what intelligent actors decide.
|
|
150
|
+
* Groups the five KB subsystems from ARCHITECTURE.md:
|
|
151
151
|
*
|
|
152
152
|
* - Event Log (immutable append-only) — via EventStore
|
|
153
153
|
* - Materialized Views (fast single-doc queries) — via ViewStorage
|
|
154
154
|
* - Content Store (working-tree files, URI-addressed) — via WorkingTreeStore
|
|
155
155
|
* - Graph (eventually consistent relationship projection) — via GraphDatabase
|
|
156
|
+
* - Graph Consumer (event-to-graph projection) — via GraphDBConsumer
|
|
156
157
|
*
|
|
157
158
|
* The Gatherer and Matcher are the only actors that read from these stores directly.
|
|
158
159
|
*/
|
|
@@ -162,14 +163,76 @@ interface KnowledgeBase {
|
|
|
162
163
|
views: ViewStorage;
|
|
163
164
|
content: WorkingTreeStore;
|
|
164
165
|
graph: GraphDatabase;
|
|
166
|
+
graphConsumer: GraphDBConsumer;
|
|
165
167
|
projectionsDir: string;
|
|
166
168
|
}
|
|
167
|
-
declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger): KnowledgeBase
|
|
169
|
+
declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger): Promise<KnowledgeBase>;
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* Stower Actor
|
|
173
|
+
*
|
|
174
|
+
* The single write gateway to the Knowledge Base. Subscribes to command
|
|
175
|
+
* events on the EventBus and translates them into domain events on the
|
|
176
|
+
* EventStore + content writes to the RepresentationStore.
|
|
177
|
+
*
|
|
178
|
+
* From ARCHITECTURE.md:
|
|
179
|
+
* The Knowledge Base has exactly three actor interfaces:
|
|
180
|
+
* - Stower (write) — this actor
|
|
181
|
+
* - Gatherer (read context)
|
|
182
|
+
* - Matcher (read search)
|
|
183
|
+
*
|
|
184
|
+
* No other code should call eventStore.appendEvent() or repStore.store().
|
|
185
|
+
*
|
|
186
|
+
* Subscriptions:
|
|
187
|
+
* - yield:create → resource.created (+ content store) → yield:created / yield:create-failed
|
|
188
|
+
* - yield:update → resource.updated (+ content store) → yield:updated / yield:update-failed
|
|
189
|
+
* - yield:mv → resource.moved (+ working tree move) → yield:moved / yield:move-failed
|
|
190
|
+
* - mark:create → annotation.added → mark:created / mark:create-failed
|
|
191
|
+
* - mark:delete → annotation.removed → mark:deleted / mark:delete-failed
|
|
192
|
+
* - mark:update-body → annotation.body.updated → (no result event yet)
|
|
193
|
+
* - mark:archive → resource.archived (+ file removal) (resource-scoped, no result event)
|
|
194
|
+
* - mark:unarchive → resource.unarchived (resource-scoped, no result event)
|
|
195
|
+
* - mark:add-entity-type → entitytype.added → mark:entity-type-added / mark:entity-type-add-failed
|
|
196
|
+
* - mark:update-entity-types → entitytag.added / entitytag.removed
|
|
197
|
+
* - job:start → job.started
|
|
198
|
+
* - job:report-progress → job.progress
|
|
199
|
+
* - job:complete → job.completed
|
|
200
|
+
* - job:fail → job.failed
|
|
201
|
+
*/
|
|
202
|
+
|
|
203
|
+
type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
|
|
204
|
+
interface CreateResourceResult {
|
|
205
|
+
resourceId: ResourceId;
|
|
206
|
+
resource: ResourceDescriptor$3;
|
|
207
|
+
}
|
|
208
|
+
declare class Stower {
|
|
209
|
+
private kb;
|
|
210
|
+
private eventBus;
|
|
211
|
+
private subscription;
|
|
212
|
+
private readonly logger;
|
|
213
|
+
constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
|
|
214
|
+
initialize(): Promise<void>;
|
|
215
|
+
private handleYieldCreate;
|
|
216
|
+
private handleYieldUpdate;
|
|
217
|
+
private handleYieldMv;
|
|
218
|
+
private handleMarkCreate;
|
|
219
|
+
private handleMarkDelete;
|
|
220
|
+
private handleMarkUpdateBody;
|
|
221
|
+
private handleMarkArchive;
|
|
222
|
+
private handleMarkUnarchive;
|
|
223
|
+
private handleAddEntityType;
|
|
224
|
+
private handleUpdateEntityTypes;
|
|
225
|
+
private handleJobStart;
|
|
226
|
+
private handleJobReportProgress;
|
|
227
|
+
private handleJobComplete;
|
|
228
|
+
private handleJobFail;
|
|
229
|
+
stop(): Promise<void>;
|
|
230
|
+
}
|
|
168
231
|
|
|
169
232
|
/**
|
|
170
233
|
* Gatherer Actor
|
|
171
234
|
*
|
|
172
|
-
*
|
|
235
|
+
* LLM context assembly for the Knowledge System. Subscribes to gather events,
|
|
173
236
|
* queries KB stores via context modules, and emits results back to the bus.
|
|
174
237
|
*
|
|
175
238
|
* From ARCHITECTURE.md:
|
|
@@ -178,70 +241,46 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
|
|
|
178
241
|
* the context needed for downstream work."
|
|
179
242
|
*
|
|
180
243
|
* Handles:
|
|
181
|
-
* - gather:requested
|
|
182
|
-
* -
|
|
183
|
-
* - browse:resources-requested — list resources
|
|
184
|
-
* - browse:annotations-requested — all annotations for a resource
|
|
185
|
-
* - browse:annotation-requested — single annotation with resolved resource
|
|
186
|
-
* - browse:events-requested — resource event history
|
|
187
|
-
* - browse:annotation-history-requested — annotation event history
|
|
188
|
-
* - mark:entity-types-requested — list entity types
|
|
244
|
+
* - gather:requested — annotation-level LLM context assembly
|
|
245
|
+
* - gather:resource-requested — resource-level LLM context assembly
|
|
189
246
|
*
|
|
190
|
-
* RxJS pipeline
|
|
191
|
-
* - groupBy(resourceUri) for per-resource isolation (gather events)
|
|
192
|
-
* - mergeMap for independent request-response (browse events)
|
|
247
|
+
* RxJS pipeline uses groupBy(resourceId) + concatMap for per-resource isolation.
|
|
193
248
|
*/
|
|
194
249
|
|
|
195
250
|
declare class Gatherer {
|
|
196
251
|
private kb;
|
|
197
252
|
private eventBus;
|
|
198
253
|
private inferenceClient;
|
|
199
|
-
private project?;
|
|
200
254
|
private subscriptions;
|
|
201
255
|
private readonly logger;
|
|
202
|
-
constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger
|
|
256
|
+
constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger);
|
|
203
257
|
initialize(): Promise<void>;
|
|
204
258
|
private handleAnnotationGather;
|
|
205
259
|
private handleResourceGather;
|
|
206
|
-
|
|
207
|
-
private handleBrowseResources;
|
|
208
|
-
private handleBrowseAnnotations;
|
|
209
|
-
private handleBrowseAnnotation;
|
|
210
|
-
private handleBrowseEvents;
|
|
211
|
-
private handleBrowseAnnotationHistory;
|
|
212
|
-
private handleEntityTypes;
|
|
260
|
+
generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId): Promise<components['schemas']['ContextualSummaryResponse']>;
|
|
213
261
|
stop(): Promise<void>;
|
|
214
262
|
}
|
|
215
263
|
|
|
216
264
|
/**
|
|
217
265
|
* Matcher Actor
|
|
218
266
|
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
* (graph, views), and emits results back to the bus.
|
|
222
|
-
*
|
|
223
|
-
* From ARCHITECTURE.md:
|
|
224
|
-
* "When an Analyst or Linker Agent emits a bind event, the Matcher receives it
|
|
225
|
-
* from the bus, searches the KB stores for matching resources, and resolves
|
|
226
|
-
* references — linking a mention to its referent."
|
|
267
|
+
* Candidate search for the bind flow. Subscribes to match:search-requested,
|
|
268
|
+
* queries the KB graph for matching resources, scores them, and emits results.
|
|
227
269
|
*
|
|
228
270
|
* Handles:
|
|
229
|
-
* -
|
|
230
|
-
* - bind:referenced-by-requested — find annotations that reference a resource
|
|
271
|
+
* - match:search-requested — multi-source retrieval + composite scoring
|
|
231
272
|
*
|
|
232
|
-
* The
|
|
233
|
-
*
|
|
234
|
-
* userId is available from auth context. That domain event still flows
|
|
235
|
-
* through the bus via EventStore auto-publish.
|
|
273
|
+
* The write side (annotation.body.updated) stays in the route where userId
|
|
274
|
+
* is available from auth context.
|
|
236
275
|
*/
|
|
237
276
|
|
|
238
277
|
declare class Matcher {
|
|
239
278
|
private kb;
|
|
240
279
|
private eventBus;
|
|
241
|
-
private inferenceClient
|
|
280
|
+
private inferenceClient;
|
|
242
281
|
private subscriptions;
|
|
243
282
|
private readonly logger;
|
|
244
|
-
constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient
|
|
283
|
+
constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient);
|
|
245
284
|
initialize(): Promise<void>;
|
|
246
285
|
private handleSearch;
|
|
247
286
|
/**
|
|
@@ -269,68 +308,45 @@ declare class Matcher {
|
|
|
269
308
|
* @returns Map of resourceId → score (0-1)
|
|
270
309
|
*/
|
|
271
310
|
private inferenceSemanticScore;
|
|
272
|
-
private handleReferencedBy;
|
|
273
311
|
stop(): Promise<void>;
|
|
274
312
|
}
|
|
275
313
|
|
|
276
314
|
/**
|
|
277
|
-
*
|
|
278
|
-
*
|
|
279
|
-
* The single write gateway to the Knowledge Base. Subscribes to command
|
|
280
|
-
* events on the EventBus and translates them into domain events on the
|
|
281
|
-
* EventStore + content writes to the RepresentationStore.
|
|
315
|
+
* Browser Actor
|
|
282
316
|
*
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
* - Stower (write) — this actor
|
|
286
|
-
* - Gatherer (read context)
|
|
287
|
-
* - Matcher (read search)
|
|
317
|
+
* Filesystem-shaped reads and KB graph reads for the Knowledge System.
|
|
318
|
+
* Merges live filesystem state with KB metadata for tracked resources.
|
|
288
319
|
*
|
|
289
|
-
*
|
|
290
|
-
*
|
|
291
|
-
*
|
|
292
|
-
* -
|
|
293
|
-
* -
|
|
294
|
-
* -
|
|
295
|
-
* -
|
|
296
|
-
* -
|
|
297
|
-
* -
|
|
298
|
-
* -
|
|
299
|
-
* - mark:unarchive → resource.unarchived (resource-scoped, no result event)
|
|
300
|
-
* - mark:add-entity-type → entitytype.added → mark:entity-type-added / mark:entity-type-add-failed
|
|
301
|
-
* - mark:update-entity-types → entitytag.added / entitytag.removed
|
|
302
|
-
* - job:start → job.started
|
|
303
|
-
* - job:report-progress → job.progress
|
|
304
|
-
* - job:complete → job.completed
|
|
305
|
-
* - job:fail → job.failed
|
|
320
|
+
* Handles:
|
|
321
|
+
* - browse:resource-requested — single resource metadata (materialized from events)
|
|
322
|
+
* - browse:resources-requested — list resources
|
|
323
|
+
* - browse:annotations-requested — all annotations for a resource
|
|
324
|
+
* - browse:annotation-requested — single annotation with resolved resource
|
|
325
|
+
* - browse:events-requested — resource event history
|
|
326
|
+
* - browse:annotation-history-requested — annotation event history
|
|
327
|
+
* - browse:referenced-by-requested — find annotations in the KB graph that reference a resource
|
|
328
|
+
* - browse:entity-types-requested — list entity types from the project projection
|
|
329
|
+
* - browse:directory-requested — list a project directory, merging fs + ViewStorage
|
|
306
330
|
*/
|
|
307
331
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
resourceId: ResourceId;
|
|
311
|
-
resource: ResourceDescriptor$3;
|
|
312
|
-
}
|
|
313
|
-
declare class Stower {
|
|
332
|
+
declare class Browser {
|
|
333
|
+
private views;
|
|
314
334
|
private kb;
|
|
315
335
|
private eventBus;
|
|
316
|
-
private
|
|
336
|
+
private project;
|
|
337
|
+
private subscriptions;
|
|
317
338
|
private readonly logger;
|
|
318
|
-
constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
|
|
339
|
+
constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
|
|
319
340
|
initialize(): Promise<void>;
|
|
320
|
-
private
|
|
321
|
-
private
|
|
322
|
-
private
|
|
323
|
-
private
|
|
324
|
-
private
|
|
325
|
-
private
|
|
326
|
-
private
|
|
327
|
-
private
|
|
328
|
-
private
|
|
329
|
-
private handleUpdateEntityTypes;
|
|
330
|
-
private handleJobStart;
|
|
331
|
-
private handleJobReportProgress;
|
|
332
|
-
private handleJobComplete;
|
|
333
|
-
private handleJobFail;
|
|
341
|
+
private handleBrowseResource;
|
|
342
|
+
private handleBrowseResources;
|
|
343
|
+
private handleBrowseAnnotations;
|
|
344
|
+
private handleBrowseAnnotation;
|
|
345
|
+
private handleBrowseEvents;
|
|
346
|
+
private handleBrowseAnnotationHistory;
|
|
347
|
+
private handleReferencedBy;
|
|
348
|
+
private handleEntityTypes;
|
|
349
|
+
private handleBrowseDirectory;
|
|
334
350
|
stop(): Promise<void>;
|
|
335
351
|
}
|
|
336
352
|
|
|
@@ -364,39 +380,53 @@ declare class CloneTokenManager {
|
|
|
364
380
|
}
|
|
365
381
|
|
|
366
382
|
/**
|
|
367
|
-
*
|
|
383
|
+
* Knowledge System
|
|
384
|
+
*
|
|
385
|
+
* Binds the KnowledgeBase to the actors that provide disciplined access to it.
|
|
386
|
+
* Nothing outside the KnowledgeSystem reads or writes the KnowledgeBase directly.
|
|
368
387
|
*
|
|
369
|
-
*
|
|
370
|
-
* -
|
|
371
|
-
* -
|
|
372
|
-
* -
|
|
388
|
+
* - kb: the durable store (event log, views, content, graph)
|
|
389
|
+
* - stower: write actor — weaves new knowledge in
|
|
390
|
+
* - gatherer: read actor — traces threads to build context
|
|
391
|
+
* - matcher: search actor — finds related threads
|
|
392
|
+
* - browser: filesystem actor — lists project directories
|
|
393
|
+
* - cloneTokenManager: token actor — manages resource clone tokens
|
|
373
394
|
*
|
|
374
|
-
*
|
|
375
|
-
* const makeMeaning = await startMakeMeaning(config);
|
|
395
|
+
* EventBus, JobQueue, and workers are peers to KnowledgeSystem, not members.
|
|
376
396
|
*/
|
|
377
397
|
|
|
378
|
-
interface
|
|
398
|
+
interface KnowledgeSystem {
|
|
379
399
|
kb: KnowledgeBase;
|
|
380
|
-
jobQueue: JobQueue;
|
|
381
|
-
eventStore: EventStore;
|
|
382
|
-
graphDb: GraphDatabase;
|
|
383
|
-
/** Inference client for the Gatherer actor — use for context-assembly operations */
|
|
384
|
-
gathererInferenceClient: InferenceClient;
|
|
385
|
-
workers: {
|
|
386
|
-
detection: ReferenceAnnotationWorker;
|
|
387
|
-
generation: GenerationWorker;
|
|
388
|
-
highlight: HighlightAnnotationWorker;
|
|
389
|
-
assessment: AssessmentAnnotationWorker;
|
|
390
|
-
comment: CommentAnnotationWorker;
|
|
391
|
-
tag: TagAnnotationWorker;
|
|
392
|
-
};
|
|
393
|
-
graphConsumer: GraphDBConsumer;
|
|
394
400
|
stower: Stower;
|
|
395
401
|
gatherer: Gatherer;
|
|
396
402
|
matcher: Matcher;
|
|
403
|
+
browser: Browser;
|
|
397
404
|
cloneTokenManager: CloneTokenManager;
|
|
398
405
|
stop: () => Promise<void>;
|
|
399
406
|
}
|
|
407
|
+
declare function stopKnowledgeSystem(ks: KnowledgeSystem): Promise<void>;
|
|
408
|
+
|
|
409
|
+
/**
|
|
410
|
+
* Make-Meaning Service
|
|
411
|
+
*
|
|
412
|
+
* Provides a clean interface:
|
|
413
|
+
* const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
|
|
414
|
+
*/
|
|
415
|
+
|
|
416
|
+
interface MakeMeaningService {
|
|
417
|
+
knowledgeSystem: KnowledgeSystem;
|
|
418
|
+
jobQueue: JobQueue;
|
|
419
|
+
workers: Workers;
|
|
420
|
+
stop: () => Promise<void>;
|
|
421
|
+
}
|
|
422
|
+
type Workers = {
|
|
423
|
+
detection: ReferenceAnnotationWorker;
|
|
424
|
+
generation: GenerationWorker;
|
|
425
|
+
highlight: HighlightAnnotationWorker;
|
|
426
|
+
assessment: AssessmentAnnotationWorker;
|
|
427
|
+
comment: CommentAnnotationWorker;
|
|
428
|
+
tag: TagAnnotationWorker;
|
|
429
|
+
};
|
|
400
430
|
declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
|
|
401
431
|
|
|
402
432
|
/**
|
|
@@ -962,4 +992,4 @@ declare function generateReferenceSuggestions(referenceTitle: string, client: In
|
|
|
962
992
|
declare const PACKAGE_NAME = "@semiont/make-meaning";
|
|
963
993
|
declare const VERSION = "0.1.0";
|
|
964
994
|
|
|
965
|
-
export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, type BackupContentReader, type BackupEventStoreReader, type BackupExporterOptions, type BackupImportResult, type BackupImporterOptions, type BackupManifestHeader, type BackupStreamSummary, type BuildContextOptions, CloneTokenManager, type ContentBlobResolver, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, FORMAT_VERSION, Gatherer, GraphContext,
|
|
995
|
+
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, 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, type MakeMeaningConfig, type MakeMeaningService, Matcher, PACKAGE_NAME, type ReplayStats, ResourceContext, ResourceOperations, Stower, type UpdateAnnotationBodyResult, type UpdateResourceInput, VERSION, bootstrapEntityTypes, createKnowledgeBase, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, resetBootstrap, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
|