@dxos/echo-memory 0.0.0-stage → 0.0.0

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 (147) hide show
  1. package/LICENSE +105 -0
  2. package/dist/lib/Fact.mjs +1 -0
  3. package/dist/lib/FactFeed.mjs +1 -0
  4. package/dist/lib/Graph.mjs +1 -0
  5. package/dist/lib/Hash.mjs +1 -0
  6. package/dist/lib/Mapping.mjs +1 -0
  7. package/dist/lib/MemoryError.mjs +1 -0
  8. package/dist/lib/MemoryQuery.mjs +1 -0
  9. package/dist/lib/MemoryService.mjs +1 -0
  10. package/dist/lib/Ontology.mjs +1 -0
  11. package/dist/lib/Pipeline.mjs +1 -0
  12. package/dist/lib/Predicate.mjs +1 -0
  13. package/dist/lib/Rdf.mjs +1 -0
  14. package/dist/lib/RdfStore.mjs +1 -0
  15. package/dist/lib/Sparql.mjs +1 -0
  16. package/dist/lib/Subscription.mjs +1 -0
  17. package/dist/lib/Trig.mjs +1 -0
  18. package/dist/lib/Vocab.mjs +1 -0
  19. package/dist/lib/Vocabularies.mjs +1 -0
  20. package/dist/lib/chunk-Fact.mjs +245 -0
  21. package/dist/lib/chunk-Fact.mjs.map +1 -0
  22. package/dist/lib/chunk-FactFeed.mjs +29 -0
  23. package/dist/lib/chunk-FactFeed.mjs.map +1 -0
  24. package/dist/lib/chunk-Graph.mjs +147 -0
  25. package/dist/lib/chunk-Graph.mjs.map +1 -0
  26. package/dist/lib/chunk-Hash.mjs +16 -0
  27. package/dist/lib/chunk-Hash.mjs.map +1 -0
  28. package/dist/lib/chunk-Mapping.mjs +226 -0
  29. package/dist/lib/chunk-Mapping.mjs.map +1 -0
  30. package/dist/lib/chunk-MemoryError.mjs +10 -0
  31. package/dist/lib/chunk-MemoryError.mjs.map +1 -0
  32. package/dist/lib/chunk-MemoryQuery.mjs +99 -0
  33. package/dist/lib/chunk-MemoryQuery.mjs.map +1 -0
  34. package/dist/lib/chunk-MemoryService.mjs +31 -0
  35. package/dist/lib/chunk-MemoryService.mjs.map +1 -0
  36. package/dist/lib/chunk-Ontology.mjs +529 -0
  37. package/dist/lib/chunk-Ontology.mjs.map +1 -0
  38. package/dist/lib/chunk-Pipeline.mjs +84 -0
  39. package/dist/lib/chunk-Pipeline.mjs.map +1 -0
  40. package/dist/lib/chunk-Predicate.mjs +66 -0
  41. package/dist/lib/chunk-Predicate.mjs.map +1 -0
  42. package/dist/lib/chunk-Rdf.mjs +120 -0
  43. package/dist/lib/chunk-Rdf.mjs.map +1 -0
  44. package/dist/lib/chunk-RdfStore.mjs +60 -0
  45. package/dist/lib/chunk-RdfStore.mjs.map +1 -0
  46. package/dist/lib/chunk-Sparql.mjs +153 -0
  47. package/dist/lib/chunk-Sparql.mjs.map +1 -0
  48. package/dist/lib/chunk-Subscription.mjs +44 -0
  49. package/dist/lib/chunk-Subscription.mjs.map +1 -0
  50. package/dist/lib/chunk-Trig.mjs +106 -0
  51. package/dist/lib/chunk-Trig.mjs.map +1 -0
  52. package/dist/lib/chunk-Vocab.mjs +164 -0
  53. package/dist/lib/chunk-Vocab.mjs.map +1 -0
  54. package/dist/lib/chunk-Vocabularies.mjs +343 -0
  55. package/dist/lib/chunk-Vocabularies.mjs.map +1 -0
  56. package/dist/lib/chunk-rolldown-runtime.mjs +13 -0
  57. package/dist/lib/index.mjs +19 -0
  58. package/dist/types/src/Fact.d.ts +339 -0
  59. package/dist/types/src/Fact.d.ts.map +1 -0
  60. package/dist/types/src/Fact.test.d.ts +2 -0
  61. package/dist/types/src/Fact.test.d.ts.map +1 -0
  62. package/dist/types/src/FactFeed.d.ts +11 -0
  63. package/dist/types/src/FactFeed.d.ts.map +1 -0
  64. package/dist/types/src/FactFeed.test.d.ts +2 -0
  65. package/dist/types/src/FactFeed.test.d.ts.map +1 -0
  66. package/dist/types/src/Graph.d.ts +31 -0
  67. package/dist/types/src/Graph.d.ts.map +1 -0
  68. package/dist/types/src/Graph.test.d.ts +2 -0
  69. package/dist/types/src/Graph.test.d.ts.map +1 -0
  70. package/dist/types/src/Hash.d.ts +3 -0
  71. package/dist/types/src/Hash.d.ts.map +1 -0
  72. package/dist/types/src/Mapping.d.ts +18 -0
  73. package/dist/types/src/Mapping.d.ts.map +1 -0
  74. package/dist/types/src/Mapping.test.d.ts +2 -0
  75. package/dist/types/src/Mapping.test.d.ts.map +1 -0
  76. package/dist/types/src/MemoryError.d.ts +33 -0
  77. package/dist/types/src/MemoryError.d.ts.map +1 -0
  78. package/dist/types/src/MemoryQuery.d.ts +136 -0
  79. package/dist/types/src/MemoryQuery.d.ts.map +1 -0
  80. package/dist/types/src/MemoryQuery.test.d.ts +2 -0
  81. package/dist/types/src/MemoryQuery.test.d.ts.map +1 -0
  82. package/dist/types/src/MemoryService.d.ts +72 -0
  83. package/dist/types/src/MemoryService.d.ts.map +1 -0
  84. package/dist/types/src/Ontology.d.ts +115 -0
  85. package/dist/types/src/Ontology.d.ts.map +1 -0
  86. package/dist/types/src/Ontology.test.d.ts +2 -0
  87. package/dist/types/src/Ontology.test.d.ts.map +1 -0
  88. package/dist/types/src/Pipeline.d.ts +103 -0
  89. package/dist/types/src/Pipeline.d.ts.map +1 -0
  90. package/dist/types/src/Predicate.d.ts +17 -0
  91. package/dist/types/src/Predicate.d.ts.map +1 -0
  92. package/dist/types/src/Predicate.test.d.ts +2 -0
  93. package/dist/types/src/Predicate.test.d.ts.map +1 -0
  94. package/dist/types/src/Rdf.d.ts +33 -0
  95. package/dist/types/src/Rdf.d.ts.map +1 -0
  96. package/dist/types/src/Rdf.test.d.ts +2 -0
  97. package/dist/types/src/Rdf.test.d.ts.map +1 -0
  98. package/dist/types/src/RdfStore.d.ts +471 -0
  99. package/dist/types/src/RdfStore.d.ts.map +1 -0
  100. package/dist/types/src/Sparql.d.ts +58 -0
  101. package/dist/types/src/Sparql.d.ts.map +1 -0
  102. package/dist/types/src/Sparql.test.d.ts +2 -0
  103. package/dist/types/src/Sparql.test.d.ts.map +1 -0
  104. package/dist/types/src/Subscription.d.ts +100 -0
  105. package/dist/types/src/Subscription.d.ts.map +1 -0
  106. package/dist/types/src/Trig.d.ts +8 -0
  107. package/dist/types/src/Trig.d.ts.map +1 -0
  108. package/dist/types/src/Trig.test.d.ts +2 -0
  109. package/dist/types/src/Trig.test.d.ts.map +1 -0
  110. package/dist/types/src/Vocab.d.ts +90 -0
  111. package/dist/types/src/Vocab.d.ts.map +1 -0
  112. package/dist/types/src/Vocabularies.d.ts +45 -0
  113. package/dist/types/src/Vocabularies.d.ts.map +1 -0
  114. package/dist/types/src/index.d.ts +19 -0
  115. package/dist/types/src/index.d.ts.map +1 -0
  116. package/dist/types/tsconfig.tsbuildinfo +1 -0
  117. package/package.json +133 -3
  118. package/src/Fact.test.ts +74 -0
  119. package/src/Fact.ts +269 -0
  120. package/src/FactFeed.test.ts +40 -0
  121. package/src/FactFeed.ts +38 -0
  122. package/src/Graph.test.ts +106 -0
  123. package/src/Graph.ts +158 -0
  124. package/src/Hash.ts +15 -0
  125. package/src/Mapping.test.ts +197 -0
  126. package/src/Mapping.ts +320 -0
  127. package/src/MemoryError.ts +10 -0
  128. package/src/MemoryQuery.test.ts +67 -0
  129. package/src/MemoryQuery.ts +114 -0
  130. package/src/MemoryService.ts +89 -0
  131. package/src/Ontology.test.ts +94 -0
  132. package/src/Ontology.ts +571 -0
  133. package/src/Pipeline.ts +97 -0
  134. package/src/Predicate.test.ts +47 -0
  135. package/src/Predicate.ts +89 -0
  136. package/src/Rdf.test.ts +104 -0
  137. package/src/Rdf.ts +158 -0
  138. package/src/RdfStore.ts +111 -0
  139. package/src/Sparql.test.ts +72 -0
  140. package/src/Sparql.ts +237 -0
  141. package/src/Subscription.ts +47 -0
  142. package/src/Trig.test.ts +199 -0
  143. package/src/Trig.ts +170 -0
  144. package/src/Vocab.ts +134 -0
  145. package/src/Vocabularies.ts +204 -0
  146. package/src/index.ts +22 -0
  147. package/README.md +0 -3
@@ -0,0 +1,571 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // @import-as-namespace
6
+
7
+ import * as Predicate from './Predicate.ts';
8
+ import * as Rdf from './Rdf.ts';
9
+ import * as Vocab from './Vocab.ts';
10
+
11
+ const { quad, namedNode, literal } = Rdf;
12
+
13
+ /**
14
+ * A predicate the brain knows: its IRI, the shorthand rules use, the surface forms that map onto it, and the RDFS /
15
+ * OWL / SKOS metadata it is described with in the ontology graph.
16
+ */
17
+ export type Entry = {
18
+ readonly iri: string;
19
+ /** Lowercase identifier rules may use as shorthand (`works_on(dima, X)`); `sx:shorthand`. */
20
+ readonly name: string;
21
+ /** `rdfs:label`. */
22
+ readonly label: string;
23
+ /** Other surface forms that name it; `skos:altLabel`. */
24
+ readonly synonyms?: ReadonlyArray<string>;
25
+ /** `rdfs:comment`. */
26
+ readonly description?: string;
27
+ /** IRI of the class the subject belongs to; `rdfs:domain`. */
28
+ readonly domain?: string;
29
+ /** IRI of the class the object belongs to; `rdfs:range`. */
30
+ readonly range?: string;
31
+ /** IRI of the predicate that states the same relation in the other direction; `owl:inverseOf`. */
32
+ readonly inverse?: string;
33
+ /**
34
+ * IRIs of predicates that mean the same; `owl:equivalentProperty`. A query for this predicate matches statements
35
+ * made with any of them, which is how predicates are merged without rewriting stored statements.
36
+ */
37
+ readonly equivalents?: ReadonlyArray<string>;
38
+ /** The vocabulary that defines it (`https://schema.org/`, a brain namespace); `rdfs:isDefinedBy`. */
39
+ readonly definedBy?: string;
40
+ /** When an extractor minted it; `dcterms:created`. */
41
+ readonly created?: string;
42
+ /** What minted it (an extractor id and model); `dcterms:creator`. */
43
+ readonly creator?: string;
44
+ /** A quote it was minted from; `skos:example`. */
45
+ readonly example?: string;
46
+ /** The predicate it was merged into; `dcterms:isReplacedBy`, with `owl:deprecated true`. */
47
+ readonly replacedBy?: string;
48
+ };
49
+
50
+ /**
51
+ * The lookup key for a surface predicate: pipeline-rdf's relation key (case, auxiliaries and head-verb
52
+ * inflection collapse) with words joined by `_`, so `Will-Work-On`, `working on` and `works_on` compare equal.
53
+ */
54
+ export const key = (surface: string): string => Predicate.normalize(words(surface)).replace(/\s+/g, '_');
55
+
56
+ /**
57
+ * The shorthand a surface predicate is minted under: {@link key} without stemming, since the stem is a matching key
58
+ * nobody reads (`changed` keys to `chang`) while the shorthand names the predicate in its IRI and in rules.
59
+ */
60
+ export const nameFor = (surface: string): string =>
61
+ Predicate.normalize(words(surface), { stem: false }).replace(/\s+/g, '_');
62
+
63
+ const words = (surface: string): string => surface.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');
64
+
65
+ const camel = (name: string): string => name.replace(/_([a-z0-9])/g, (_, char: string) => char.toUpperCase());
66
+
67
+ /** The IRI a predicate shorthand mints to in a namespace, e.g. `works_on` → `dx:worksOn`. */
68
+ export const iriFor = (name: string, namespace: string = Vocab.DX): string => `${namespace}${camel(name)}`;
69
+
70
+ /** An entry for a predicate shorthand; the IRI defaults to the `dx:` vocabulary. */
71
+ export const entry = (
72
+ name: string,
73
+ options: Omit<Entry, 'iri' | 'name' | 'label'> & { iri?: string; label?: string } = {},
74
+ ): Entry => ({
75
+ ...options,
76
+ iri: options.iri ?? iriFor(name),
77
+ name,
78
+ label: options.label ?? name.replace(/_/g, ' '),
79
+ definedBy: options.definedBy ?? (options.iri === undefined ? Vocab.DX : undefined),
80
+ });
81
+
82
+ export type OntologyOptions = {
83
+ /** Where predicates the ontology does not know are minted: the brain's own namespace. */
84
+ readonly namespace?: string;
85
+ };
86
+
87
+ /**
88
+ * An extensible set of predicates. A surface form the ontology does not know mints a predicate in the ontology's
89
+ * namespace (its brain's) from its relation key, so two documents that phrase a relation the same way still share
90
+ * one predicate, and a predicate one brain invented never poses as a shared vocabulary term.
91
+ */
92
+ export class Ontology {
93
+ readonly entries: ReadonlyArray<Entry>;
94
+ readonly namespace: string;
95
+ readonly #byKey = new Map<string, Entry>();
96
+ readonly #byIri = new Map<string, Entry>();
97
+
98
+ /** @throws Error when two entries claim one surface form or one IRI. */
99
+ constructor(entries: ReadonlyArray<Entry>, { namespace = Vocab.LOCAL_BRAIN }: OntologyOptions = {}) {
100
+ this.entries = entries;
101
+ this.namespace = namespace;
102
+ for (const entry of entries) {
103
+ if (this.#byIri.has(entry.iri)) {
104
+ throw new Error(`Predicate defined twice: ${entry.iri}`);
105
+ }
106
+ this.#byIri.set(entry.iri, entry);
107
+ }
108
+ // Equivalents resolve to the entry naming them, unless an entry of their own defines them.
109
+ for (const entry of entries) {
110
+ for (const equivalent of entry.equivalents ?? []) {
111
+ if (!this.#byIri.has(equivalent)) {
112
+ this.#byIri.set(equivalent, entry);
113
+ }
114
+ }
115
+ }
116
+ for (const entry of entries) {
117
+ // A merged-away predicate keeps its IRI readable but no longer claims surface forms.
118
+ if (entry.replacedBy !== undefined) {
119
+ continue;
120
+ }
121
+ for (const surface of [entry.name, entry.label, ...(entry.synonyms ?? [])]) {
122
+ const existing = this.#byKey.get(key(surface));
123
+ if (existing !== undefined && existing.iri !== entry.iri) {
124
+ throw new Error(`Synonym ${surface} maps to both ${existing.name} and ${entry.name}`);
125
+ }
126
+ this.#byKey.set(key(surface), entry);
127
+ }
128
+ }
129
+ }
130
+
131
+ /** The entry a surface form names, if the ontology knows it. */
132
+ find(surface: string): Entry | undefined {
133
+ return this.#byKey.get(key(surface));
134
+ }
135
+
136
+ /** The entry for an IRI (its own, or one it is equivalent to), if the ontology defines it. */
137
+ get(iri: string): Entry | undefined {
138
+ return this.#byIri.get(iri);
139
+ }
140
+
141
+ /** The entry an IRI stands for: a merged-away predicate's survivor, else its own entry. */
142
+ canonical(iri: string): Entry | undefined {
143
+ let entry = this.get(iri);
144
+ const seen = new Set<string>();
145
+ while (entry?.replacedBy !== undefined && !seen.has(entry.iri)) {
146
+ seen.add(entry.iri);
147
+ entry = this.get(entry.replacedBy) ?? entry;
148
+ }
149
+ return entry;
150
+ }
151
+
152
+ /** The IRIs a query for this predicate matches: its own and every equivalent, either way round. */
153
+ equivalents(iri: string): Set<string> {
154
+ const entry = this.canonical(iri);
155
+ const iris = new Set([iri]);
156
+ if (entry) {
157
+ iris.add(entry.iri);
158
+ for (const equivalent of entry.equivalents ?? []) {
159
+ iris.add(equivalent);
160
+ }
161
+ for (const other of this.entries) {
162
+ if (other.replacedBy === entry.iri) {
163
+ iris.add(other.iri);
164
+ }
165
+ }
166
+ }
167
+ return iris;
168
+ }
169
+
170
+ /** The entry for a surface form; one the ontology does not know is minted in its namespace, labelled with the form. */
171
+ resolve(surface: string): Entry {
172
+ const known = this.find(surface);
173
+ if (known) {
174
+ return known;
175
+ }
176
+ const name = nameFor(surface);
177
+ return { iri: iriFor(name, this.namespace), name, label: surface.trim(), definedBy: this.namespace };
178
+ }
179
+
180
+ /** A new ontology with these entries added; an entry for a known IRI replaces it. */
181
+ extend(entries: ReadonlyArray<Entry>): Ontology {
182
+ const iris = new Set(entries.map(({ iri }) => iri));
183
+ return new Ontology([...this.entries.filter(({ iri }) => !iris.has(iri)), ...entries], {
184
+ namespace: this.namespace,
185
+ });
186
+ }
187
+
188
+ /**
189
+ * A new ontology with the predicates a brain has learned added: unlike {@link extend}, an entry this ontology
190
+ * already defines, or whose surface form it already maps, is skipped rather than rejected, since a store may hold
191
+ * predicates minted before the seed vocabulary named them.
192
+ */
193
+ include(entries: ReadonlyArray<Entry>): Ontology {
194
+ const learned: Entry[] = [];
195
+ const surfaces = new Set<string>();
196
+ for (const entry of entries) {
197
+ const forms = [entry.name, entry.label, ...(entry.synonyms ?? [])].map(key);
198
+ if (this.get(entry.iri) || forms.some((form) => this.#byKey.has(form) || surfaces.has(form))) {
199
+ continue;
200
+ }
201
+ forms.forEach((form) => surfaces.add(form));
202
+ learned.push(entry);
203
+ }
204
+ return learned.length === 0 ? this : this.extend(learned);
205
+ }
206
+
207
+ /** The same predicates, minting new ones in another namespace. */
208
+ withNamespace(namespace: string): Ontology {
209
+ return new Ontology(this.entries, { namespace });
210
+ }
211
+
212
+ /**
213
+ * Merges one predicate into another: the survivor gains the other's IRI as an equivalent and its surface forms as
214
+ * synonyms, and the other is kept, deprecated, so stored statements made with it still read and match.
215
+ * @throws Error when either IRI is not an entry of this ontology.
216
+ */
217
+ merge(from: string, into: string): Ontology {
218
+ const source = this.entries.find(({ iri }) => iri === from);
219
+ const target = this.entries.find(({ iri }) => iri === into);
220
+ if (!source || !target) {
221
+ throw new Error(`Cannot merge ${from} into ${into}: both must be defined.`);
222
+ }
223
+ const forms = new Set([target.name, target.label, ...(target.synonyms ?? [])].map(key));
224
+ const merged: Entry = {
225
+ ...target,
226
+ synonyms: [
227
+ ...(target.synonyms ?? []),
228
+ ...[source.name, source.label, ...(source.synonyms ?? [])].filter((form) => !forms.has(key(form))),
229
+ ].filter((form, index, all) => all.findIndex((other) => key(other) === key(form)) === index),
230
+ equivalents: [...new Set([...(target.equivalents ?? []), source.iri, ...(source.equivalents ?? [])])],
231
+ };
232
+ const deprecated: Entry = { ...source, synonyms: [], equivalents: [], replacedBy: into };
233
+ return new Ontology(
234
+ this.entries.map((entry) => (entry.iri === into ? merged : entry.iri === from ? deprecated : entry)),
235
+ { namespace: this.namespace },
236
+ );
237
+ }
238
+ }
239
+
240
+ /** Creates an ontology. */
241
+ export const make = (entries: ReadonlyArray<Entry>, options?: OntologyOptions): Ontology =>
242
+ new Ontology(entries, options);
243
+
244
+ /** The label an IRI reads as when no ontology defines it: its local name, split into words. */
245
+ export const labelFromIri = (iri: string): string =>
246
+ iri
247
+ .replace(/^.*[#/]/, '')
248
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
249
+ .toLowerCase();
250
+
251
+ //
252
+ // The ontology graph: every predicate is an `rdf:Property` described with RDFS, OWL, SKOS and DCMI terms, in a
253
+ // graph of its own (`Vocab.ONTOLOGY_GRAPH`) so the vocabulary is never mixed into the statements that use it.
254
+ //
255
+
256
+ const ontologyGraph = () => namedNode(Vocab.ONTOLOGY_GRAPH);
257
+
258
+ /** The entry as quads in the ontology graph. */
259
+ export const toQuads = (entry: Entry): Rdf.Quad[] => {
260
+ const subject = namedNode(entry.iri);
261
+ const quads: Rdf.Quad[] = [];
262
+ const add = (predicate: string, object: Rdf.NamedNode | Rdf.Literal) =>
263
+ quads.push(quad(subject, namedNode(predicate), object, ontologyGraph()));
264
+ add(Vocab.RDF_TYPE, namedNode(Vocab.RDF_PROPERTY));
265
+ add(Vocab.RDFS_LABEL, literal(entry.label));
266
+ add(Vocab.SX_SHORTHAND, literal(entry.name));
267
+ for (const synonym of entry.synonyms ?? []) {
268
+ add(Vocab.SKOS_ALT_LABEL, literal(synonym));
269
+ }
270
+ const iris: ReadonlyArray<[string, string | undefined]> = [
271
+ [Vocab.RDFS_DOMAIN, entry.domain],
272
+ [Vocab.RDFS_RANGE, entry.range],
273
+ [Vocab.OWL_INVERSE_OF, entry.inverse],
274
+ [Vocab.RDFS_IS_DEFINED_BY, entry.definedBy],
275
+ [Vocab.DCTERMS_IS_REPLACED_BY, entry.replacedBy],
276
+ ];
277
+ for (const [predicate, value] of iris) {
278
+ if (value !== undefined) {
279
+ add(predicate, namedNode(value));
280
+ }
281
+ }
282
+ for (const equivalent of entry.equivalents ?? []) {
283
+ add(Vocab.OWL_EQUIVALENT_PROPERTY, namedNode(equivalent));
284
+ }
285
+ const literals: ReadonlyArray<[string, string | undefined]> = [
286
+ [Vocab.RDFS_COMMENT, entry.description],
287
+ [Vocab.DCTERMS_CREATED, entry.created],
288
+ [Vocab.DCTERMS_CREATOR, entry.creator],
289
+ [Vocab.SKOS_EXAMPLE, entry.example],
290
+ ];
291
+ for (const [predicate, value] of literals) {
292
+ if (value !== undefined) {
293
+ add(predicate, literal(value));
294
+ }
295
+ }
296
+ if (entry.replacedBy !== undefined) {
297
+ add(Vocab.OWL_DEPRECATED, literal('true', namedNode(`${Vocab.XSD}boolean`)));
298
+ }
299
+ return quads;
300
+ };
301
+
302
+ /**
303
+ * The entries described in the ontology graph, one per subject; the inverse of {@link toQuads}. A predicate known
304
+ * only by its label (as facts store a minted one) reads with the shorthand its label keys to. Multi-valued fields
305
+ * keep their first value where an entry holds one value.
306
+ */
307
+ export const fromQuads = (quads: readonly Rdf.Quad[]): Entry[] => {
308
+ const subjects = new Map<string, Map<string, string[]>>();
309
+ for (const entry of quads) {
310
+ if (entry.graph.value !== Vocab.ONTOLOGY_GRAPH || entry.subject.termType !== 'NamedNode') {
311
+ continue;
312
+ }
313
+ let props = subjects.get(entry.subject.value);
314
+ if (!props) {
315
+ subjects.set(entry.subject.value, (props = new Map()));
316
+ }
317
+ const values = props.get(entry.predicate.value) ?? [];
318
+ if (!values.includes(entry.object.value)) {
319
+ props.set(entry.predicate.value, [...values, entry.object.value]);
320
+ }
321
+ }
322
+ return [...subjects].flatMap(([iri, props]) => {
323
+ const one = (predicate: string) => props.get(predicate)?.[0];
324
+ const many = (predicate: string) => props.get(predicate) ?? [];
325
+ const label = one(Vocab.RDFS_LABEL) ?? labelFromIri(iri);
326
+ const optional = {
327
+ synonyms: many(Vocab.SKOS_ALT_LABEL),
328
+ equivalents: many(Vocab.OWL_EQUIVALENT_PROPERTY),
329
+ description: one(Vocab.RDFS_COMMENT),
330
+ domain: one(Vocab.RDFS_DOMAIN),
331
+ range: one(Vocab.RDFS_RANGE),
332
+ inverse: one(Vocab.OWL_INVERSE_OF),
333
+ definedBy: one(Vocab.RDFS_IS_DEFINED_BY),
334
+ created: one(Vocab.DCTERMS_CREATED),
335
+ creator: one(Vocab.DCTERMS_CREATOR),
336
+ example: one(Vocab.SKOS_EXAMPLE),
337
+ replacedBy: one(Vocab.DCTERMS_IS_REPLACED_BY),
338
+ };
339
+ return [
340
+ {
341
+ iri,
342
+ name: one(Vocab.SX_SHORTHAND) ?? nameFor(label),
343
+ label,
344
+ ...Object.fromEntries(
345
+ Object.entries(optional).filter(([, value]) =>
346
+ Array.isArray(value) ? value.length > 0 : value !== undefined,
347
+ ),
348
+ ),
349
+ },
350
+ ];
351
+ });
352
+ };
353
+
354
+ /** Every entry of the ontology as quads in the ontology graph. */
355
+ export const ontologyQuads = (ontology: Ontology): Rdf.Quad[] => ontology.entries.flatMap(toQuads);
356
+
357
+ //
358
+ // The seed vocabulary. A predicate an established vocabulary defines is used under that vocabulary's own IRI, so
359
+ // the brain's graph reads as schema.org / FOAF / Dublin Core to any RDF tool; `dx:` holds only the relations no
360
+ // such vocabulary has (an agent's memories and actions). Each seed lists the `dx:` IRI it was stored under before
361
+ // it moved to the external one as an equivalent, so earlier statements still match.
362
+ //
363
+
364
+ const schema = (name: string) => `${Vocab.SCHEMA}${name}`;
365
+ const dx = (name: string) => `${Vocab.DX}${name}`;
366
+
367
+ const PERSON = schema('Person');
368
+ const ORGANIZATION = schema('Organization');
369
+ const PLACE = schema('Place');
370
+
371
+ /** The starter predicates: people and organizations, plus the relations agent goals are written against. */
372
+ export const DEFAULT_ENTRIES: ReadonlyArray<Entry> = [
373
+ // RDF / RDFS: class membership.
374
+ entry('is_a', {
375
+ iri: Vocab.RDF_TYPE,
376
+ label: 'is a',
377
+ synonyms: ['is an', 'is instance of'],
378
+ description: 'A class the subject is an instance of: "Socrates is a man".',
379
+ definedBy: Vocab.RDF,
380
+ equivalents: [dx('isA')],
381
+ }),
382
+ entry('kind_of', {
383
+ iri: `${Vocab.RDFS}subClassOf`,
384
+ label: 'kind of',
385
+ synonyms: ['is kind of', 'is type of', 'is a type of', 'subclass of'],
386
+ description:
387
+ 'A broader class every instance of the subject class belongs to: "a philosopher is a kind of thinker".',
388
+ definedBy: Vocab.RDFS,
389
+ }),
390
+ entry('same_as', {
391
+ iri: Vocab.OWL_SAME_AS,
392
+ label: 'same as',
393
+ synonyms: ['also known as', 'aka', 'is the same as'],
394
+ description: 'The subject and object are one and the same entity.',
395
+ definedBy: Vocab.OWL,
396
+ }),
397
+
398
+ // schema.org: people and organizations.
399
+ entry('has_role', {
400
+ iri: schema('jobTitle'),
401
+ label: 'has role',
402
+ synonyms: ['works as', 'is on the team as', 'role', 'job title'],
403
+ description: 'The role or job title the subject holds.',
404
+ domain: PERSON,
405
+ definedBy: Vocab.SCHEMA,
406
+ equivalents: [dx('hasRole')],
407
+ }),
408
+ entry('member_of', {
409
+ iri: schema('memberOf'),
410
+ synonyms: ['belongs to', 'is member of', 'is on the team', 'is on team'],
411
+ description: 'The organization or team the subject belongs to.',
412
+ domain: PERSON,
413
+ range: ORGANIZATION,
414
+ inverse: schema('member'),
415
+ definedBy: Vocab.SCHEMA,
416
+ equivalents: [dx('memberOf'), `${Vocab.ORG}memberOf`],
417
+ }),
418
+ entry('has_member', {
419
+ iri: schema('member'),
420
+ description: 'A member of the organization or team.',
421
+ domain: ORGANIZATION,
422
+ range: PERSON,
423
+ inverse: schema('memberOf'),
424
+ definedBy: Vocab.SCHEMA,
425
+ equivalents: [dx('hasMember'), `${Vocab.ORG}hasMember`],
426
+ }),
427
+ entry('works_for', {
428
+ iri: schema('worksFor'),
429
+ synonyms: ['works at', 'employed by', 'is employed at'],
430
+ description: 'The organization that employs the subject.',
431
+ domain: PERSON,
432
+ range: ORGANIZATION,
433
+ definedBy: Vocab.SCHEMA,
434
+ }),
435
+ entry('founded', {
436
+ synonyms: ['is founder of', 'established', 'started'],
437
+ description: 'An organization the subject founded; schema.org states it the other way round (`schema:founder`).',
438
+ domain: PERSON,
439
+ range: ORGANIZATION,
440
+ inverse: schema('founder'),
441
+ }),
442
+ entry('alumni_of', {
443
+ iri: schema('alumniOf'),
444
+ label: 'alumni of',
445
+ synonyms: ['studied at', 'graduated from'],
446
+ description: 'A school or organization (never a person) the subject studied at or was formerly part of.',
447
+ domain: PERSON,
448
+ range: ORGANIZATION,
449
+ definedBy: Vocab.SCHEMA,
450
+ }),
451
+ entry('knows_about', {
452
+ iri: schema('knowsAbout'),
453
+ synonyms: ['is expert in', 'is the one to ask about', 'expert in', 'specializes in'],
454
+ description: 'An area the subject can answer questions about.',
455
+ definedBy: Vocab.SCHEMA,
456
+ equivalents: [dx('knowsAbout')],
457
+ }),
458
+ entry('located_in', {
459
+ iri: schema('location'),
460
+ synonyms: ['lives in', 'is based in', 'based in', 'is located in'],
461
+ description: 'Where the subject is.',
462
+ range: PLACE,
463
+ definedBy: Vocab.SCHEMA,
464
+ equivalents: [dx('locatedIn')],
465
+ }),
466
+ entry('born_in', {
467
+ iri: schema('birthPlace'),
468
+ synonyms: ['was born in', 'birthplace'],
469
+ description: 'The place the subject was born.',
470
+ domain: PERSON,
471
+ range: PLACE,
472
+ definedBy: Vocab.SCHEMA,
473
+ }),
474
+ entry('about', {
475
+ iri: schema('about'),
476
+ synonyms: ['is about', 'concerns', 'covers'],
477
+ description: 'The topic a document, message or event is about.',
478
+ definedBy: Vocab.SCHEMA,
479
+ }),
480
+ entry('mentions', {
481
+ iri: schema('mentions'),
482
+ synonyms: ['refers to', 'cites'],
483
+ description: 'An entity a document or message mentions without being about it.',
484
+ definedBy: Vocab.SCHEMA,
485
+ }),
486
+ entry('text', {
487
+ iri: schema('text'),
488
+ label: 'has text',
489
+ synonyms: ['wording'],
490
+ description: 'The wording of a message, question or document.',
491
+ definedBy: Vocab.SCHEMA,
492
+ }),
493
+
494
+ // FOAF: social relations and accounts.
495
+ entry('knows', {
496
+ iri: `${Vocab.FOAF}knows`,
497
+ synonyms: ['is friends with', 'is acquainted with', 'met'],
498
+ description: 'A person the subject knows.',
499
+ domain: PERSON,
500
+ range: PERSON,
501
+ definedBy: Vocab.FOAF,
502
+ equivalents: [schema('knows')],
503
+ }),
504
+ entry('has_account', {
505
+ iri: `${Vocab.FOAF}account`,
506
+ synonyms: ['is on discord as', 'username', 'handle'],
507
+ description: 'An account the subject uses, such as a Discord username.',
508
+ definedBy: Vocab.FOAF,
509
+ equivalents: [dx('hasAccount')],
510
+ }),
511
+
512
+ // Dublin Core: works and their parts.
513
+ entry('created_by', {
514
+ iri: `${Vocab.DCTERMS}creator`,
515
+ synonyms: ['authored by', 'written by', 'made by'],
516
+ description: 'Who made the subject (a document, a project, a thing).',
517
+ range: PERSON,
518
+ definedBy: Vocab.DCTERMS,
519
+ }),
520
+ entry('part_of', {
521
+ iri: `${Vocab.DCTERMS}isPartOf`,
522
+ synonyms: ['is part of', 'component of'],
523
+ description: 'A larger whole the subject is part of.',
524
+ definedBy: Vocab.DCTERMS,
525
+ }),
526
+ entry('depends_on', {
527
+ iri: `${Vocab.DCTERMS}requires`,
528
+ synonyms: ['requires', 'needs'],
529
+ description: 'Something the subject cannot work or happen without.',
530
+ definedBy: Vocab.DCTERMS,
531
+ }),
532
+ entry('related_to', {
533
+ iri: `${Vocab.SKOS}related`,
534
+ synonyms: ['is related to', 'is associated with'],
535
+ description: 'An associative link when no more specific predicate fits.',
536
+ definedBy: Vocab.SKOS,
537
+ }),
538
+
539
+ // dx: what an agent records and does, which no shared vocabulary names.
540
+ entry('claim', { description: 'A remembered statement about the subject, in the agent’s words.' }),
541
+ entry('has_note', { label: 'has note', description: 'Notes about the subject, in markdown.' }),
542
+ entry('helps_with', { synonyms: ['will help with', 'helping with'], description: 'Work the subject helps with.' }),
543
+ entry('works_on', {
544
+ synonyms: ['working on', 'will work on'],
545
+ description: 'A project or task the subject is working on.',
546
+ }),
547
+ entry('uses', {
548
+ synonyms: ['is using', 'built with', 'adopted', 'switched to', 'relies on'],
549
+ description: 'A library, tool, language or service the subject uses (a person, a project or a codebase).',
550
+ // Extractors minted it in the local brain before it was seeded; the equivalence keeps those statements matching.
551
+ equivalents: [iriFor('uses', Vocab.LOCAL_BRAIN)],
552
+ }),
553
+ entry('completed', { synonyms: ['finished', 'done'], description: 'A task the subject finished.' }),
554
+ entry('shipped', { synonyms: ['ships', 'released'], description: 'Something the subject released.' }),
555
+ entry('proposes', { synonyms: ['suggests'], description: 'An idea or change the subject put forward.' }),
556
+ entry('asked', {
557
+ synonyms: ['asks', 'asked question'],
558
+ description: 'A question the subject asked: a node typed schema:Question whose `has text` is its wording.',
559
+ }),
560
+ entry('received', { description: 'Something the subject was sent.' }),
561
+ entry('archived', { description: 'Something the subject archived.' }),
562
+ entry('deleted', { description: 'Something the subject deleted.' }),
563
+ entry('filed', { description: 'Something the subject filed (an issue, a report).' }),
564
+ entry('drafted', { description: 'Something the subject drafted.' }),
565
+ entry('notified', { description: 'Someone the subject notified.' }),
566
+ entry('relayed', { description: 'A message the subject passed on.' }),
567
+ entry('awaiting', { synonyms: ['waiting for'], description: 'Something the subject is waiting for.' }),
568
+ ];
569
+
570
+ /** The starter ontology. */
571
+ export const DEFAULT: Ontology = make(DEFAULT_ENTRIES);
@@ -0,0 +1,97 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // @import-as-namespace
6
+
7
+ import * as Effect from 'effect/Effect';
8
+ import * as Option from 'effect/Option';
9
+ import * as Schema from 'effect/Schema';
10
+
11
+ import * as Rdf from './Rdf.ts';
12
+ import * as Trig from './Trig.ts';
13
+ import * as Vocab from './Vocab.ts';
14
+
15
+ /** One source a pipeline read (a Discord channel or thread): how far it read and what it found there. */
16
+ export const Source = Schema.Struct({
17
+ id: Schema.String,
18
+ label: Schema.optional(Schema.String),
19
+ /** Where reading stopped, as the source names its items (a Discord message id). */
20
+ cursor: Schema.optional(Schema.String),
21
+ firstItemAt: Schema.optional(Schema.String),
22
+ lastItemAt: Schema.optional(Schema.String),
23
+ items: Schema.Number,
24
+ status: Schema.optional(Schema.String),
25
+ });
26
+ export type Source = Schema.Schema.Type<typeof Source>;
27
+
28
+ /** What one stage spent on one model. */
29
+ export const ModelUsage = Schema.Struct({
30
+ model: Schema.String,
31
+ calls: Schema.Number,
32
+ inputTokens: Schema.Number,
33
+ outputTokens: Schema.Number,
34
+ cacheReadTokens: Schema.Number,
35
+ cacheWriteTokens: Schema.Number,
36
+ /** At catalog prices; absent for a model the catalog does not price. */
37
+ costUsd: Schema.optional(Schema.Number),
38
+ });
39
+ export type ModelUsage = Schema.Schema.Type<typeof ModelUsage>;
40
+
41
+ export const Stage = Schema.Struct({
42
+ id: Schema.String,
43
+ label: Schema.String,
44
+ /** Position in the pipeline, from 0. */
45
+ order: Schema.Number,
46
+ /** Items the stage passed to the next one. */
47
+ items: Schema.optional(Schema.Number),
48
+ startedAt: Schema.optional(Schema.String),
49
+ endedAt: Schema.optional(Schema.String),
50
+ models: Schema.Array(ModelUsage),
51
+ });
52
+ export type Stage = Schema.Schema.Type<typeof Stage>;
53
+
54
+ /**
55
+ * What a fact-producing run did, kept in the fact store beside the facts it produced: the sources it read and how
56
+ * far, its stages in order, the models each called and at what cost, how long it took and how many facts it wrote.
57
+ */
58
+ export const State = Schema.Struct({
59
+ name: Schema.String,
60
+ status: Schema.String,
61
+ startedAt: Schema.optional(Schema.String),
62
+ endedAt: Schema.optional(Schema.String),
63
+ sources: Schema.Array(Source),
64
+ stages: Schema.Array(Stage),
65
+ facts: Schema.optional(Schema.Number),
66
+ });
67
+ export type State = Schema.Schema.Type<typeof State>;
68
+
69
+ /** The named graph a run's state lives in, outside every fact's graph. */
70
+ export const GRAPH = `${Vocab.GRAPH}pipeline`;
71
+
72
+ /** The predicate carrying the state, as one JSON literal: it is read whole, never queried field by field. */
73
+ export const STATE = `${Vocab.SX}pipelineState`;
74
+
75
+ const JSON_DATATYPE = `${Vocab.RDF}JSON`;
76
+
77
+ /** The quad storing `state`; importing it into a store replaces nothing, so a store holds one state per run name. */
78
+ export const toQuads = (state: State): Rdf.Quad[] => [
79
+ Rdf.quad(
80
+ Rdf.namedNode(`${GRAPH}/${encodeURIComponent(state.name)}`),
81
+ Rdf.namedNode(STATE),
82
+ Rdf.literal(JSON.stringify(state), Rdf.namedNode(JSON_DATATYPE)),
83
+ Rdf.namedNode(GRAPH),
84
+ ),
85
+ ];
86
+
87
+ /** `state` as a TriG document, which a store imports beside the facts the run wrote. */
88
+ export const toTrig = (state: State): Effect.Effect<string> => Effect.sync(() => Trig.write(toQuads(state)));
89
+
90
+ /** Selects every stored run state as `?state`. */
91
+ export const SPARQL = `SELECT ?state WHERE { GRAPH <${GRAPH}> { ?run <${STATE}> ?state } }`;
92
+
93
+ const decode = Schema.decodeUnknownOption(Schema.fromJsonString(State));
94
+
95
+ /** The run states among `values` (each a `?state` literal from {@link SPARQL}); a malformed one is skipped. */
96
+ export const fromValues = (values: readonly string[]): State[] =>
97
+ values.flatMap((value) => Option.toArray(decode(value)));