@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
package/package.json CHANGED
@@ -1,6 +1,136 @@
1
1
  {
2
2
  "name": "@dxos/echo-memory",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.0",
4
+ "description": "Memory interface: the MemoryService tag, the attributed fact data model and typed memory queries.",
5
+ "homepage": "https://dxos.org",
6
+ "bugs": "https://github.com/dxos/dxos/issues",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/dxos/dxos"
10
+ },
11
+ "license": "FSL-1.1-Apache-2.0",
12
+ "author": "DXOS.org",
13
+ "sideEffects": false,
14
+ "type": "module",
15
+ "exports": {
16
+ ".": {
17
+ "source": "./src/index.ts",
18
+ "types": "./dist/types/src/index.d.ts",
19
+ "import": "./dist/lib/index.mjs"
20
+ },
21
+ "./Fact": {
22
+ "source": "./src/Fact.ts",
23
+ "types": "./dist/types/src/Fact.d.ts",
24
+ "import": "./dist/lib/Fact.mjs"
25
+ },
26
+ "./FactFeed": {
27
+ "source": "./src/FactFeed.ts",
28
+ "types": "./dist/types/src/FactFeed.d.ts",
29
+ "import": "./dist/lib/FactFeed.mjs"
30
+ },
31
+ "./Graph": {
32
+ "source": "./src/Graph.ts",
33
+ "types": "./dist/types/src/Graph.d.ts",
34
+ "import": "./dist/lib/Graph.mjs"
35
+ },
36
+ "./Hash": {
37
+ "source": "./src/Hash.ts",
38
+ "types": "./dist/types/src/Hash.d.ts",
39
+ "import": "./dist/lib/Hash.mjs"
40
+ },
41
+ "./Mapping": {
42
+ "source": "./src/Mapping.ts",
43
+ "types": "./dist/types/src/Mapping.d.ts",
44
+ "import": "./dist/lib/Mapping.mjs"
45
+ },
46
+ "./MemoryError": {
47
+ "source": "./src/MemoryError.ts",
48
+ "types": "./dist/types/src/MemoryError.d.ts",
49
+ "import": "./dist/lib/MemoryError.mjs"
50
+ },
51
+ "./MemoryQuery": {
52
+ "source": "./src/MemoryQuery.ts",
53
+ "types": "./dist/types/src/MemoryQuery.d.ts",
54
+ "import": "./dist/lib/MemoryQuery.mjs"
55
+ },
56
+ "./MemoryService": {
57
+ "source": "./src/MemoryService.ts",
58
+ "types": "./dist/types/src/MemoryService.d.ts",
59
+ "import": "./dist/lib/MemoryService.mjs"
60
+ },
61
+ "./Ontology": {
62
+ "source": "./src/Ontology.ts",
63
+ "types": "./dist/types/src/Ontology.d.ts",
64
+ "import": "./dist/lib/Ontology.mjs"
65
+ },
66
+ "./Pipeline": {
67
+ "source": "./src/Pipeline.ts",
68
+ "types": "./dist/types/src/Pipeline.d.ts",
69
+ "import": "./dist/lib/Pipeline.mjs"
70
+ },
71
+ "./Predicate": {
72
+ "source": "./src/Predicate.ts",
73
+ "types": "./dist/types/src/Predicate.d.ts",
74
+ "import": "./dist/lib/Predicate.mjs"
75
+ },
76
+ "./Rdf": {
77
+ "source": "./src/Rdf.ts",
78
+ "types": "./dist/types/src/Rdf.d.ts",
79
+ "import": "./dist/lib/Rdf.mjs"
80
+ },
81
+ "./RdfStore": {
82
+ "source": "./src/RdfStore.ts",
83
+ "types": "./dist/types/src/RdfStore.d.ts",
84
+ "import": "./dist/lib/RdfStore.mjs"
85
+ },
86
+ "./Sparql": {
87
+ "source": "./src/Sparql.ts",
88
+ "types": "./dist/types/src/Sparql.d.ts",
89
+ "import": "./dist/lib/Sparql.mjs"
90
+ },
91
+ "./Subscription": {
92
+ "source": "./src/Subscription.ts",
93
+ "types": "./dist/types/src/Subscription.d.ts",
94
+ "import": "./dist/lib/Subscription.mjs"
95
+ },
96
+ "./Trig": {
97
+ "source": "./src/Trig.ts",
98
+ "types": "./dist/types/src/Trig.d.ts",
99
+ "import": "./dist/lib/Trig.mjs"
100
+ },
101
+ "./Vocab": {
102
+ "source": "./src/Vocab.ts",
103
+ "types": "./dist/types/src/Vocab.d.ts",
104
+ "import": "./dist/lib/Vocab.mjs"
105
+ },
106
+ "./Vocabularies": {
107
+ "source": "./src/Vocabularies.ts",
108
+ "types": "./dist/types/src/Vocabularies.d.ts",
109
+ "import": "./dist/lib/Vocabularies.mjs"
110
+ },
111
+ "./package.json": "./package.json"
112
+ },
113
+ "types": "dist/types/src/index.d.ts",
114
+ "files": [
115
+ "dist",
116
+ "src"
117
+ ],
118
+ "dependencies": {
119
+ "@dxos/errors": "0.16.0",
120
+ "@dxos/keys": "0.16.0",
121
+ "@rdfjs/types": "^2.0.1"
122
+ },
123
+ "devDependencies": {
124
+ "@effect/vitest": "4.0.4",
125
+ "@types/n3": "^1.26.1",
126
+ "effect": "4.0.4",
127
+ "n3": "2.1.0",
128
+ "vitest": "4.1.10"
129
+ },
130
+ "peerDependencies": {
131
+ "effect": "4.0.4"
132
+ },
133
+ "publishConfig": {
134
+ "access": "public"
135
+ }
6
136
  }
@@ -0,0 +1,74 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import * as Schema from 'effect/Schema';
6
+ import { describe, test } from 'vitest';
7
+
8
+ import * as Fact from './Fact.ts';
9
+
10
+ /** A fact as `@dxos/pipeline-rdf` writes it today: plain strings, no brands. */
11
+ const STORED = {
12
+ id: 'fact-1',
13
+ graph: 'https://dxos.org/semantic/graph/g1',
14
+ assertion: {
15
+ subject: { kind: 'entity', entity: 'alice', label: 'Alice', type: 'person' },
16
+ predicate: 'joins',
17
+ object: { kind: 'entity', entity: 'acme' },
18
+ validFrom: '2026-01-01',
19
+ quote: 'I think Alice will probably join Acme in January.',
20
+ },
21
+ factuality: { value: 'PR+', polarity: '+', confidence: 0.7 },
22
+ attribution: { agent: 'bob', source: 'dxn:queue:space:msg-1', generatedAtTime: '2026-11-03T10:00:00.000Z' },
23
+ recordedAt: '2026-11-16T10:00:00.000Z',
24
+ extractor: { id: 'default', model: 'model', version: '1' },
25
+ sourceHash: 'abc',
26
+ };
27
+
28
+ const make = (overrides: Partial<Fact.Fact> = {}): Fact.Fact => ({ ...Fact.decode([STORED])[0], ...overrides });
29
+
30
+ describe('Fact', () => {
31
+ test('a fact stored before the move decodes unchanged', ({ expect }) => {
32
+ const [fact] = Fact.decode([STORED]);
33
+ expect(fact).toEqual(STORED);
34
+ });
35
+
36
+ test('the encoded form is plain JSON', ({ expect }) => {
37
+ const fact = make();
38
+ const json = JSON.parse(JSON.stringify(Schema.encodeSync(Fact.Fact)(fact)));
39
+ expect(Schema.decodeUnknownSync(Fact.Fact)(json)).toEqual(fact);
40
+ });
41
+
42
+ test('a malformed fact fails to decode', ({ expect }) => {
43
+ expect(() => Fact.decode([{ ...STORED, factuality: { value: 'XX', polarity: '+' } }])).toThrow();
44
+ });
45
+
46
+ test('currentFacts drops superseded, retracted, expired and free-text graphs', ({ expect }) => {
47
+ const graph = (name: string) => Fact.GraphIri.make(`https://dxos.org/semantic/graph/${name}`);
48
+ const kept = make({ id: Fact.FactId.make('kept'), graph: graph('kept') });
49
+ const superseded = make({ id: Fact.FactId.make('old'), graph: graph('old') });
50
+ const retracted = make({ id: Fact.FactId.make('gone'), graph: graph('gone') });
51
+ const reviser = make({
52
+ id: Fact.FactId.make('new'),
53
+ graph: graph('new'),
54
+ supersedes: [graph('old')],
55
+ retracts: [graph('gone')],
56
+ });
57
+ const expired = make({
58
+ id: Fact.FactId.make('expired'),
59
+ graph: graph('expired'),
60
+ assertion: { ...STORED_ASSERTION, validTo: '2026-01-01' },
61
+ });
62
+ const memory = make({ id: Fact.FactId.make('memory'), graph: graph('memory'), kind: 'preference' });
63
+
64
+ const current = Fact.currentFacts([kept, superseded, retracted, reviser, expired, memory], '2026-11-16T00:00:00Z');
65
+ expect(current.map(({ id }) => id)).toEqual(['kept', 'new']);
66
+ });
67
+
68
+ test('factText reads a fact as one line', ({ expect }) => {
69
+ expect(Fact.factText(make())).toBe('Alice joins acme');
70
+ expect(Fact.factText(make({ factuality: { value: 'CT-', polarity: '-' } }))).toBe('not: Alice joins acme');
71
+ });
72
+ });
73
+
74
+ const STORED_ASSERTION = Fact.decode([STORED])[0].assertion;
package/src/Fact.ts ADDED
@@ -0,0 +1,269 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // @import-as-namespace
6
+
7
+ import * as Schema from 'effect/Schema';
8
+
9
+ //
10
+ // Identifiers. Branded so one kind of id cannot be passed for another; the encoded form stays a plain string, so
11
+ // facts stored before the brands existed still decode.
12
+ //
13
+
14
+ /** A statement's id, derived from its graph and the statement. */
15
+ export const FactId = Schema.String.pipe(Schema.brand('@dxos/echo-memory/FactId'));
16
+ export type FactId = Schema.Schema.Type<typeof FactId>;
17
+
18
+ /** The IRI of a named graph. */
19
+ export const GraphIri = Schema.String.pipe(Schema.brand('@dxos/echo-memory/GraphIri'));
20
+ export type GraphIri = Schema.Schema.Type<typeof GraphIri>;
21
+
22
+ /** An entity: an absolute IRI where one is known (`echo://…`, `did:…`, `mailto:…`, a URL), else a normalized slug. */
23
+ export const EntityKey = Schema.String.pipe(Schema.brand('@dxos/echo-memory/EntityKey'));
24
+ export type EntityKey = Schema.Schema.Type<typeof EntityKey>;
25
+
26
+ /** The item facts were read from, or a source read into facts: a DXN or another URI. */
27
+ export const SourceUri = Schema.String.pipe(Schema.brand('@dxos/echo-memory/SourceUri'));
28
+ export type SourceUri = Schema.Schema.Type<typeof SourceUri>;
29
+
30
+ //
31
+ // Terms.
32
+ //
33
+
34
+ export const EntityKind = Schema.Literals(['person', 'org', 'place', 'event', 'concept', 'thing']);
35
+ export type EntityKind = Schema.Schema.Type<typeof EntityKind>;
36
+
37
+ /** A reference to an entity: `entity` is its key, `label` the surface form kept for display. */
38
+ export const EntityTerm = Schema.Struct({
39
+ kind: Schema.Literal('entity'),
40
+ entity: EntityKey,
41
+ label: Schema.optional(Schema.String),
42
+ /** What sort of thing the extractor took it for. */
43
+ type: Schema.optional(EntityKind),
44
+ });
45
+ export interface EntityTerm extends Schema.Schema.Type<typeof EntityTerm> {}
46
+
47
+ /** A literal value. */
48
+ export const LiteralTerm = Schema.Struct({
49
+ kind: Schema.Literal('literal'),
50
+ literal: Schema.String,
51
+ });
52
+ export interface LiteralTerm extends Schema.Schema.Type<typeof LiteralTerm> {}
53
+
54
+ /** A subject or object: an entity reference or a literal, tagged by `kind`. */
55
+ export const Term = Schema.Union([EntityTerm, LiteralTerm]);
56
+ export type Term = Schema.Schema.Type<typeof Term>;
57
+
58
+ /** A resolved entity. */
59
+ export const Entity = Schema.Struct({
60
+ id: EntityKey,
61
+ kind: EntityKind,
62
+ label: Schema.String,
63
+ aliases: Schema.Array(Schema.String),
64
+ /** DXN of a canonical ECHO object, once resolved. */
65
+ ref: Schema.optional(Schema.String),
66
+ });
67
+ export interface Entity extends Schema.Schema.Type<typeof Entity> {}
68
+
69
+ //
70
+ // The parts of a fact.
71
+ //
72
+
73
+ /** The proposition: subject, predicate, object, and when it holds in the world. */
74
+ export const Assertion = Schema.Struct({
75
+ subject: Term,
76
+ /** The predicate's label: the surface form, or the ontology's label once stored. */
77
+ predicate: Schema.String,
78
+ /** The predicate's IRI; resolved from `predicate` through the ontology when absent. */
79
+ predicateIri: Schema.optional(Schema.String),
80
+ /** What a minted predicate means, as its extractor defined it. */
81
+ predicateDescription: Schema.optional(Schema.String),
82
+ object: Term,
83
+ /** ISO date from which the asserted state holds. */
84
+ validFrom: Schema.optional(Schema.String),
85
+ /** ISO date until which the asserted state holds. */
86
+ validTo: Schema.optional(Schema.String),
87
+ /** The source text it was read from. */
88
+ quote: Schema.optional(Schema.String),
89
+ });
90
+ export interface Assertion extends Schema.Schema.Type<typeof Assertion> {}
91
+
92
+ /** FactBank values: a degree (CT certain, PR probable, PS possible) with a polarity, plus CTu and Uu (uncommitted). */
93
+ export const FactualityValue = Schema.Literals(['CT+', 'CT-', 'PR+', 'PR-', 'PS+', 'PS-', 'CTu', 'Uu']);
94
+ export type FactualityValue = Schema.Schema.Type<typeof FactualityValue>;
95
+
96
+ /** The speaker's epistemic commitment to the proposition. */
97
+ export const Factuality = Schema.Struct({
98
+ value: FactualityValue,
99
+ polarity: Schema.Literals(['+', '-', '?']),
100
+ /** The extractor's confidence in its reading, 0..1. */
101
+ confidence: Schema.optional(Schema.Number.pipe(Schema.check(Schema.isBetween({ minimum: 0, maximum: 1 })))),
102
+ nature: Schema.optional(Schema.Literals(['epistemic', 'aleatory'])),
103
+ });
104
+ export interface Factuality extends Schema.Schema.Type<typeof Factuality> {}
105
+
106
+ /** Searle's illocutionary forces, minus `declarative`. */
107
+ export const IllocutionaryForce = Schema.Literals(['assertive', 'directive', 'commissive', 'expressive']);
108
+ export type IllocutionaryForce = Schema.Schema.Type<typeof IllocutionaryForce>;
109
+
110
+ /** The speech act the source performed; `mood` tells a question from a request. */
111
+ export const Illocution = Schema.Struct({
112
+ force: IllocutionaryForce,
113
+ mood: Schema.optional(Schema.Literals(['declarative', 'interrogative', 'imperative'])),
114
+ /** Who is asked to act or answer; the message's recipient when absent. */
115
+ addressee: Schema.optional(Schema.String),
116
+ });
117
+ export interface Illocution extends Schema.Schema.Type<typeof Illocution> {}
118
+
119
+ /** PROV-O-named provenance. */
120
+ export const Attribution = Schema.Struct({
121
+ /** Who said it. */
122
+ agent: Schema.optional(EntityKey),
123
+ /** The speaker's display name; `agent` stays the join key. */
124
+ agentLabel: Schema.optional(Schema.String),
125
+ source: SourceUri,
126
+ /** When it was said (ISO). */
127
+ generatedAtTime: Schema.String,
128
+ wasDerivedFrom: Schema.optional(Schema.Array(Schema.String)),
129
+ span: Schema.optional(Schema.Struct({ start: Schema.Number, end: Schema.Number })),
130
+ });
131
+ export interface Attribution extends Schema.Schema.Type<typeof Attribution> {}
132
+
133
+ //
134
+ // Fact.
135
+ //
136
+
137
+ /**
138
+ * One statement and what is known about it. Statements that share their provenance live in one named graph
139
+ * (`graph`), which carries that provenance once; a fact without a graph is the only statement of its own.
140
+ */
141
+ export const Fact = Schema.Struct({
142
+ id: FactId,
143
+ graph: Schema.optional(GraphIri),
144
+ assertion: Assertion,
145
+ factuality: Factuality,
146
+ /** Absent ⇒ assertive. */
147
+ illocution: Schema.optional(Illocution),
148
+ attribution: Attribution,
149
+ /** When memory stored it (ISO transaction time). */
150
+ recordedAt: Schema.String,
151
+ extractor: Schema.Struct({ id: Schema.String, model: Schema.String, version: Schema.String }),
152
+ /** Hash of the source content read, so a changed source is read again. */
153
+ sourceHash: Schema.String,
154
+ /** Extraction pass id, grouping the facts one run produced. */
155
+ pass: Schema.optional(Schema.String),
156
+ /** What sort of free-text memory the graph records (`preference`, `commitment`); absent for a fact. */
157
+ kind: Schema.optional(Schema.String),
158
+ /** Whether the speaker said it (`stated`) or the agent concluded it (`inferred`). */
159
+ origin: Schema.optional(Schema.String),
160
+ /** The graphs this one replaces. */
161
+ supersedes: Schema.optional(Schema.Array(GraphIri)),
162
+ /** The graphs this one withdraws. */
163
+ retracts: Schema.optional(Schema.Array(GraphIri)),
164
+ });
165
+ export interface Fact extends Schema.Schema.Type<typeof Fact> {}
166
+
167
+ /** A fact before the id brands are applied: every id a plain string, as stored and as written by hand. */
168
+ export type Encoded = Schema.Codec.Encoded<typeof Fact>;
169
+
170
+ /** A term before the id brands are applied, as a hand-built fact's {@link Encoded} assertion holds it. */
171
+ export type EncodedTerm = Schema.Codec.Encoded<typeof Term>;
172
+
173
+ /** An entity term before the id brands are applied. */
174
+ export type EncodedEntityTerm = Schema.Codec.Encoded<typeof EntityTerm>;
175
+
176
+ /** Builds a fact from its plain form, applying the id brands; throws on a malformed fact. */
177
+ export const make: (fact: Encoded) => Fact = Schema.decodeSync(Fact);
178
+
179
+ /** {@link make} over a list, so a literal list of facts is still checked against {@link Encoded}. */
180
+ export const makeMany = (facts: readonly Encoded[]): Fact[] => facts.map((fact) => make(fact));
181
+
182
+ /** Decodes facts from their JSON form, applying the id brands; throws on a malformed fact. */
183
+ export const decode = Schema.decodeUnknownSync(Schema.Array(Fact));
184
+
185
+ //
186
+ // Ontology.
187
+ //
188
+
189
+ /** A predicate a memory knows, as its ontology graph describes it (RDFS / OWL / SKOS). */
190
+ export const PredicateEntry = Schema.Struct({
191
+ iri: Schema.String,
192
+ /** Lowercase shorthand rules use, e.g. `works_on`. */
193
+ name: Schema.String,
194
+ label: Schema.String,
195
+ synonyms: Schema.optional(Schema.Array(Schema.String)),
196
+ description: Schema.optional(Schema.String),
197
+ domain: Schema.optional(Schema.String),
198
+ range: Schema.optional(Schema.String),
199
+ inverse: Schema.optional(Schema.String),
200
+ equivalents: Schema.optional(Schema.Array(Schema.String)),
201
+ definedBy: Schema.optional(Schema.String),
202
+ created: Schema.optional(Schema.String),
203
+ creator: Schema.optional(Schema.String),
204
+ example: Schema.optional(Schema.String),
205
+ replacedBy: Schema.optional(Schema.String),
206
+ });
207
+ export interface PredicateEntry extends Schema.Schema.Type<typeof PredicateEntry> {}
208
+
209
+ //
210
+ // Reading facts without a store.
211
+ //
212
+
213
+ /** Prefix of the IRI a fact with no graph of its own is stored under. */
214
+ const FACT_IRI_PREFIX = 'https://dxos.org/semantic/fact/';
215
+
216
+ /** The graph a fact's statement lives in: its own graph, else the graph of the fact alone. */
217
+ export const graphOf = (fact: Fact): GraphIri =>
218
+ fact.graph ?? GraphIri.make(FACT_IRI_PREFIX + encodeURIComponent(fact.id));
219
+
220
+ /** Whether a graph still holds: another graph can replace it (`supersedes`) or withdraw it (`retracts`). */
221
+ export const GraphStatus = Schema.Literals(['active', 'superseded', 'retracted']);
222
+ export type GraphStatus = Schema.Schema.Type<typeof GraphStatus>;
223
+
224
+ /** The status of every graph the facts mention, by graph IRI. */
225
+ export const graphStatus = (facts: readonly Fact[]): Map<GraphIri, GraphStatus> => {
226
+ const statuses = new Map<GraphIri, GraphStatus>(facts.map((fact) => [graphOf(fact), 'active']));
227
+ for (const fact of facts) {
228
+ for (const superseded of fact.supersedes ?? []) {
229
+ if (statuses.get(superseded) !== 'retracted') {
230
+ statuses.set(superseded, 'superseded');
231
+ }
232
+ }
233
+ }
234
+ for (const fact of facts) {
235
+ for (const retracted of fact.retracts ?? []) {
236
+ statuses.set(retracted, 'retracted');
237
+ }
238
+ }
239
+ return statuses;
240
+ };
241
+
242
+ /**
243
+ * The facts that still hold at `now` (ISO): none in a superseded or retracted graph, none past its `validTo`, and
244
+ * none in a graph with a `kind`, which records a free-text memory rather than a fact.
245
+ */
246
+ export const currentFacts = (facts: readonly Fact[], now: string): Fact[] => {
247
+ const statuses = graphStatus(facts);
248
+ const at = Date.parse(now);
249
+ return facts.filter(
250
+ (fact) =>
251
+ fact.kind === undefined && statuses.get(graphOf(fact)) === 'active' && holdsAt(fact.assertion.validTo, at),
252
+ );
253
+ };
254
+
255
+ /** Compared as instants, since extracted `validTo`s vary in offset and precision; one that does not parse is kept. */
256
+ const holdsAt = (validTo: string | undefined, now: number): boolean => {
257
+ const until = validTo === undefined ? Number.NaN : Date.parse(validTo);
258
+ return Number.isNaN(until) || until > now;
259
+ };
260
+
261
+ /** The value a term contributes as a join key: the entity key, else the literal. */
262
+ export const termValue = (term: Term): string => (term.kind === 'entity' ? term.entity : term.literal);
263
+
264
+ /** The text of a term, for display. */
265
+ export const termText = (term: Term): string => (term.kind === 'entity' ? (term.label ?? term.entity) : term.literal);
266
+
267
+ /** A fact as one line: subject, predicate, object; a negated fact is marked "not:". */
268
+ export const factText = (fact: Fact): string =>
269
+ `${fact.factuality.polarity === '-' ? 'not: ' : ''}${termText(fact.assertion.subject)} ${fact.assertion.predicate} ${termText(fact.assertion.object)}`;
@@ -0,0 +1,40 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { SpaceId } from '@dxos/keys';
8
+
9
+ import * as FactFeed from './FactFeed.ts';
10
+ import type * as RdfStore from './RdfStore.ts';
11
+
12
+ describe('FactFeed', () => {
13
+ test('every replica derives the same feed id for a space, and another space gets its own', ({ expect }) => {
14
+ const spaceId = SpaceId.random();
15
+ expect(FactFeed.feedId(spaceId)).toBe(FactFeed.feedId(spaceId));
16
+ expect(FactFeed.feedId(spaceId)).not.toBe(FactFeed.feedId(SpaceId.random()));
17
+ });
18
+
19
+ test('a batch survives a block round trip', ({ expect }) => {
20
+ const batch: RdfStore.Batch = {
21
+ id: 'b1',
22
+ writes: [
23
+ {
24
+ _tag: 'insert',
25
+ quads: [
26
+ {
27
+ s: { termType: 'NamedNode', value: 'https://example.com/dima' },
28
+ p: { termType: 'NamedNode', value: 'https://example.com/name' },
29
+ o: { termType: 'Literal', value: 'Dima', language: 'en' },
30
+ g: { termType: 'NamedNode', value: 'https://example.com/g1' },
31
+ },
32
+ ],
33
+ },
34
+ { _tag: 'delete', quads: [] },
35
+ { _tag: 'clear' },
36
+ ],
37
+ };
38
+ expect(FactFeed.decodeBlock(FactFeed.encodeBlock(batch))).toEqual(batch);
39
+ });
40
+ });
@@ -0,0 +1,38 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // @import-as-namespace
6
+
7
+ import * as Schema from 'effect/Schema';
8
+
9
+ import { EntityId, type SpaceId } from '@dxos/keys';
10
+
11
+ import * as RdfStore from './RdfStore.ts';
12
+
13
+ //
14
+ // A space's fact feed: the log a memory's shared part is written to before it is applied, replicated like any feed so
15
+ // every replica of the space's memory (each device's, EDGE's) applies the same batches in the same order. It is the
16
+ // only feed of facts; each block is one `RdfStore.Batch`.
17
+ //
18
+
19
+ /** The feed namespace a space's fact feed lives in (`FeedProtocol.WellKnownNamespaces.facts`). */
20
+ export const NAMESPACE = 'facts';
21
+
22
+ /** Seed of the id of a space's fact feed, which every replica derives the same way so the feed replicates as one. */
23
+ const FEED_SEED = 'org.dxos.memory.facts';
24
+
25
+ /** The id of a space's fact feed. */
26
+ export const feedId = (spaceId: SpaceId): EntityId => EntityId.deterministic(FEED_SEED, spaceId);
27
+
28
+ const encodeBatch = Schema.encodeSync(RdfStore.Batch);
29
+ const decodeBatch = Schema.decodeUnknownSync(RdfStore.Batch);
30
+ const textEncoder = new TextEncoder();
31
+ const textDecoder = new TextDecoder();
32
+
33
+ /** A batch as a block payload: the UTF-8 JSON of the encoded batch. */
34
+ export const encodeBlock = (batch: RdfStore.Batch): Uint8Array =>
35
+ textEncoder.encode(JSON.stringify(encodeBatch(batch)));
36
+
37
+ /** Inverse of {@link encodeBlock}. */
38
+ export const decodeBlock = (data: Uint8Array): RdfStore.Batch => decodeBatch(JSON.parse(textDecoder.decode(data)));
@@ -0,0 +1,106 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import * as Fact from './Fact.ts';
8
+ import * as Graph from './Graph.ts';
9
+ import * as Mapping from './Mapping.ts';
10
+ import * as Ontology from './Ontology.ts';
11
+ import * as Vocab from './Vocab.ts';
12
+
13
+ const fact = (id: string, quote: string, object = 'founder'): Fact.Fact =>
14
+ Fact.make({
15
+ id,
16
+ assertion: {
17
+ subject: { kind: 'entity', entity: 'rich', label: 'Rich' },
18
+ predicate: 'has role',
19
+ object: { kind: 'entity', entity: object },
20
+ quote,
21
+ },
22
+ factuality: { value: 'CT+', polarity: '+' },
23
+ attribution: { source: 'https://dxos.org/team', generatedAtTime: '2026-10-13T00:00:00Z' },
24
+ recordedAt: '2026-10-13T00:00:00Z',
25
+ extractor: { id: 'default', model: 'm', version: '1' },
26
+ sourceHash: 'h',
27
+ });
28
+
29
+ describe('Graph', () => {
30
+ test('statements with the same provenance share a graph; a different quote starts another', ({ expect }) => {
31
+ const [first, second, third] = Graph.assign([
32
+ fact('a', 'Rich is the founder and CEO.'),
33
+ fact('b', 'Rich is the founder and CEO.', 'ceo'),
34
+ fact('c', 'Rich leads product.', 'product-lead'),
35
+ ]);
36
+ expect(first.graph).toBe(second.graph);
37
+ expect(third.graph).not.toBe(first.graph);
38
+ expect(first.graph).toMatch(/^https:\/\/dxos\.org\/semantic\/graph\//);
39
+ expect(first.assertion.predicateIri).toBe('https://schema.org/jobTitle');
40
+ });
41
+
42
+ test('a graph is superseded or retracted by a later one', ({ expect }) => {
43
+ const [old, other] = Graph.assign([fact('a', 'one'), fact('b', 'two')]);
44
+ const [replacement] = Graph.assign([{ ...fact('c', 'three'), supersedes: [old.graph!] }]);
45
+ const [withdrawal] = Graph.assign([{ ...fact('d', 'four'), retracts: [other.graph!] }]);
46
+ const statuses = Fact.graphStatus([old, other, replacement, withdrawal]);
47
+ expect(statuses.get(old.graph!)).toBe('superseded');
48
+ expect(statuses.get(other.graph!)).toBe('retracted');
49
+ expect(statuses.get(replacement.graph!)).toBe('active');
50
+ });
51
+
52
+ test('writes TriG: the statement inside its graph, the provenance about it', ({ expect }) => {
53
+ const trig = Graph.toTriG(Graph.assign([fact('a', 'Rich is the founder.')]));
54
+ expect(trig).toContain('g1:rich schema:jobTitle g1:founder');
55
+ expect(trig).toMatch(/graph:[^\s]+ \{/);
56
+ expect(trig).toContain('sx:quote "Rich is the founder."');
57
+ });
58
+
59
+ test('an unresolved entity is local to its graph; a stable IRI is shared', ({ expect }) => {
60
+ const [first, second] = Graph.assign([fact('a', 'Rich is the founder.'), fact('b', 'Rich founded DXOS.')]);
61
+ const subjects = [first, second].map((placed) => Mapping.factToTriples(placed)[0].subject.value);
62
+ expect(subjects[0]).toBe(`${first.graph}#rich`);
63
+ expect(subjects[1]).toBe(`${second.graph}#rich`);
64
+
65
+ const resolved = (placed: Fact.Fact): Fact.Fact =>
66
+ Fact.make({
67
+ ...placed,
68
+ assertion: { ...placed.assertion, subject: { kind: 'entity', entity: 'echo://SPACE/RICH', label: 'Rich' } },
69
+ });
70
+ const shared = [first, second].map((placed) => Mapping.factToTriples(resolved(placed))[0].subject.value);
71
+ expect(shared).toEqual(['echo://SPACE/RICH', 'echo://SPACE/RICH']);
72
+ // Read back, the local entity is its slug again.
73
+ expect(Mapping.triplesToFacts(Mapping.factToTriples(first))[0].assertion.subject).toEqual(first.assertion.subject);
74
+ });
75
+
76
+ test("a minted predicate is described in the ontology graph, outside the statement's graph", ({ expect }) => {
77
+ const ontology = Ontology.DEFAULT.withNamespace(Vocab.brainNamespace('agent-1'));
78
+ const [placed] = Graph.assign(
79
+ [
80
+ {
81
+ ...fact('a', 'Rich mentors Dima.', 'dima'),
82
+ assertion: {
83
+ ...fact('a', 'Rich mentors Dima.', 'dima').assertion,
84
+ predicate: 'mentors',
85
+ predicateDescription: 'A person the subject guides in their work.',
86
+ },
87
+ },
88
+ ],
89
+ { ontology },
90
+ );
91
+ expect(placed.assertion.predicateIri).toBe('https://dxos.org/semantic/brain/agent-1/mentors');
92
+ const quads = Mapping.factToTriples(placed, ontology);
93
+ const definition = quads.filter((quad) => quad.subject.value === placed.assertion.predicateIri);
94
+ expect(definition.every((quad) => quad.graph.value === Vocab.ONTOLOGY_GRAPH)).toBe(true);
95
+ expect(Ontology.fromQuads(definition)).toEqual([
96
+ {
97
+ iri: 'https://dxos.org/semantic/brain/agent-1/mentors',
98
+ name: 'mentors',
99
+ label: 'mentors',
100
+ description: 'A person the subject guides in their work.',
101
+ definedBy: 'https://dxos.org/semantic/brain/agent-1/',
102
+ },
103
+ ]);
104
+ expect(Graph.toTriG([placed], ontology)).toContain('brain:mentors');
105
+ });
106
+ });