mdld-parse 0.9.9 → 1.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.
- package/README.md +242 -330
- package/dist/index.js +1793 -1336
- package/package.json +4 -4
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +0 -1
- package/dist/README.md +0 -500
- package/dist/docs/API.md +0 -435
- package/dist/docs/Architecture.md +0 -190
- package/dist/docs/Guide.md +0 -816
- package/dist/docs/LLM-MDLD-Inducer.md +0 -550
- package/dist/docs/LiterateRDF.md +0 -472
- package/dist/docs/Parser.md +0 -720
- package/dist/docs/Performance.md +0 -238
- package/dist/docs/Spec-render.md +0 -1439
- package/dist/docs/Subject.md +0 -180
- package/dist/docs/Syntax.md +0 -463
- package/dist/docs/TodoList.md +0 -215
- package/dist/docs/Use-Cases.md +0 -354
- package/dist/docs/guide-m.md +0 -56
- package/dist/docs/index.html +0 -108
- package/dist/docs/index.md +0 -56
- package/dist/docs/one-page.md +0 -322
- package/dist/docs/origin.md +0 -460
- package/dist/docs/polarity.md +0 -586
- package/dist/docs/primary-subject.md +0 -326
- package/dist/docs/statements.md +0 -226
- package/dist/docs/tokenization-performance-report.md +0 -164
- package/dist/examples/Cookbook.md +0 -32
- package/dist/examples/Status-SHACL.md +0 -31
- package/dist/examples/demo/index.md +0 -35
- package/dist/examples/demo/journal.md +0 -58
- package/dist/examples/demo/minimal.md +0 -23
- package/dist/examples/demo/project.md +0 -84
- package/dist/examples/demo/prov.md +0 -107
- package/dist/examples/demo/rdf.md +0 -69
- package/dist/examples/demo/recipe.md +0 -50
- package/dist/examples/demo/research.md +0 -84
- package/dist/examples/demo/shacl.md +0 -161
- package/dist/examples/demo/space-mission.md +0 -58
- package/dist/examples/demo/tasks.md +0 -175
- package/dist/examples/demo/xsd.md +0 -91
- package/dist/examples/dogfood.md +0 -288
- package/dist/examples/few-shot.md +0 -309
- package/dist/examples/graph/rdf-graph.html +0 -473
- package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
- package/dist/examples/index.md +0 -45
- package/dist/examples/llm-time-workflow.md +0 -173
- package/dist/examples/statements.md +0 -43
- package/dist/examples/workflow.md +0 -150
- package/dist/index.html +0 -3049
- package/dist/logo.svg +0 -7
- package/dist/spec/Spec-compact.md +0 -368
- package/dist/spec/Spec-ultra.md +0 -232
- package/dist/spec/Spec.md +0 -1116
- package/dist/spec/index.md +0 -46
package/dist/docs/polarity.md
DELETED
|
@@ -1,586 +0,0 @@
|
|
|
1
|
-
# Polarity & Retraction System
|
|
2
|
-
|
|
3
|
-
MD-LD includes a **sophisticated polarity system** that enables diff authoring and document evolution through explicit `+` and `-` prefixes on predicates and types.
|
|
4
|
-
|
|
5
|
-
## Core Concepts
|
|
6
|
-
|
|
7
|
-
### Polarity Types
|
|
8
|
-
|
|
9
|
-
- **Positive (`+`)**: Default polarity, adds triples to the graph
|
|
10
|
-
- **Negative (`-`)**: Removes triples, either intra-document or external retractions
|
|
11
|
-
|
|
12
|
-
### Polarity Forms
|
|
13
|
-
|
|
14
|
-
| Form | Positive | Negative | Use Case |
|
|
15
|
-
|------|-----------|-----------|-----------|
|
|
16
|
-
| `p` | `{p}` | `{-p}` | Literal properties |
|
|
17
|
-
| `?p` | `{?p}` | `{-?p}` | Object properties |
|
|
18
|
-
| `!p` | `{!p}` | `{-!p}` | Reverse properties |
|
|
19
|
-
| `.Class` | `{.Class}` | `-.Class}` | Type declarations (subject only) |
|
|
20
|
-
|
|
21
|
-
### Resolution Behavior
|
|
22
|
-
|
|
23
|
-
- **Intra-document cancel**: When negative matches existing positive → both removed
|
|
24
|
-
- **External retract**: When negative has no matching positive → becomes external retract
|
|
25
|
-
- **Merge resolution**: External retractions cancel positives from prior documents
|
|
26
|
-
|
|
27
|
-
## Polarity Syntax Patterns
|
|
28
|
-
|
|
29
|
-
### 1. Literal Property Polarity (-p)
|
|
30
|
-
|
|
31
|
-
```markdown
|
|
32
|
-
[ex] <http://example.org/>
|
|
33
|
-
|
|
34
|
-
# Document {=ex:doc}
|
|
35
|
-
|
|
36
|
-
[Alice] {label} // Add name
|
|
37
|
-
[Alice] {-label} // Remove name (intra-document cancel)
|
|
38
|
-
[Bob] {label} // Add Bob's name
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
**Result:**
|
|
42
|
-
```javascript
|
|
43
|
-
const result = parse({ text: markdown });
|
|
44
|
-
console.log(result.quads.map(q => `${q.object.value} ${q.predicate.value}`));
|
|
45
|
-
// ['Bob http://www.w3.org/2000/01/rdf-schema#label']
|
|
46
|
-
console.log(result.remove.length); // 0 (cancelled in-stream)
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
### 2. Object Property Polarity (-?p)
|
|
50
|
-
|
|
51
|
-
```markdown
|
|
52
|
-
[ex] <http://example.org/>
|
|
53
|
-
|
|
54
|
-
# Document {=ex:doc}
|
|
55
|
-
|
|
56
|
-
[Alice] {+ex:alice ?author} // Alice is author
|
|
57
|
-
[Bob] {+ex:bob ?author} // Bob is author
|
|
58
|
-
[Bob] {-?author} // Remove Bob as author
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
**Result:**
|
|
62
|
-
```javascript
|
|
63
|
-
const result = parse({ text: markdown });
|
|
64
|
-
console.log(result.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value.split('/').pop()}`));
|
|
65
|
-
// ['doc author bob']
|
|
66
|
-
console.log(result.remove.length); // 0 (cancelled in-stream)
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
### 3. Reverse Property Polarity (-!p)
|
|
70
|
-
|
|
71
|
-
**Important**: Reverse properties need proper subject context and object declarations:
|
|
72
|
-
|
|
73
|
-
```markdown
|
|
74
|
-
[ex] <http://example.org/>
|
|
75
|
-
|
|
76
|
-
# Document
|
|
77
|
-
|
|
78
|
-
Parent: [Alice] {=ex:alice .prov:Person label}
|
|
79
|
-
Child: [Bob] {+ex:bob !ex:hasParent}
|
|
80
|
-
|
|
81
|
-
Child is not [Bob] {+ex:bob -!ex:hasParent}, it's [Bryan] {+ex:bryan !ex:hasParent}.
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
**Result:**
|
|
85
|
-
```javascript
|
|
86
|
-
const result = parse({ text: markdown });
|
|
87
|
-
console.log(result.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value.split('/').pop()}`));
|
|
88
|
-
// ['alice rdf:type prov#Person', 'alice label Alice', 'bryan hasParent alice']
|
|
89
|
-
console.log(result.remove.length); // 0 (cancelled in-stream)
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
**Why this works:**
|
|
93
|
-
- `Parent: [Alice] {=ex:alice .prov:Person label}` - Creates Alice as Person with label
|
|
94
|
-
- `Child: [Bob] {+ex:bob !ex:hasParent}` - Creates Bob with reverse relationship to Alice
|
|
95
|
-
- `[Bob] {+ex:bob -!ex:hasParent}` - Retracts Bob's hasParent relationship
|
|
96
|
-
- `[Bryan] {+ex:bryan !ex:hasParent}` - Creates Bryan with reverse relationship to Alice
|
|
97
|
-
|
|
98
|
-
### 4. Type Polarity (-.Class)
|
|
99
|
-
|
|
100
|
-
Type retractions work both in subject declarations and as standalone annotations:
|
|
101
|
-
|
|
102
|
-
```markdown
|
|
103
|
-
[ex] <http://example.org/>
|
|
104
|
-
|
|
105
|
-
# Document
|
|
106
|
-
Parent: [Alice] {=ex:alice .prov:Person label}
|
|
107
|
-
is [employed] {.ex:Employee}
|
|
108
|
-
Child: [Bob] {+ex:bob !ex:hasParent}
|
|
109
|
-
|
|
110
|
-
Is no more an [Employee] {-.ex:Employee}, but a [unemployed] {.ex:Unemployed}.
|
|
111
|
-
|
|
112
|
-
The child is not [Bob] {+ex:bob -!ex:hasParent}, it's [Bryan] {+ex:bryan !ex:hasParent}.
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
**Result:**
|
|
116
|
-
```javascript
|
|
117
|
-
const result = parse({ text: markdown });
|
|
118
|
-
console.log(result.quads.map(q => `${q.subject.value.split('/').pop()} rdf:type ${q.object.value.split('/').pop()}`));
|
|
119
|
-
// ['alice rdf:type prov#Person', 'alice rdf:type Unemployed']
|
|
120
|
-
console.log(result.remove.length); // 0 (cancelled in-stream)
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
**Expected Turtle:**
|
|
124
|
-
```turtle
|
|
125
|
-
@prefix ex: <http://example.org/>.
|
|
126
|
-
|
|
127
|
-
ex:alice a prov:Person, ex:Unemployed;
|
|
128
|
-
rdfs:label "Alice".
|
|
129
|
-
ex:bryan ex:hasParent ex:alice.
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
### 5. Mixed Polarity (Same Annotation)
|
|
133
|
-
|
|
134
|
-
Combine add and remove operations in single annotation:
|
|
135
|
-
|
|
136
|
-
```markdown
|
|
137
|
-
[ex] <http://example.org/>
|
|
138
|
-
|
|
139
|
-
# Document {=ex:doc -.ex:Draft .ex:Published -ex:version}
|
|
140
|
-
[2.0] {ex:version}
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
**Result:**
|
|
144
|
-
```javascript
|
|
145
|
-
const result = parse({ text: markdown });
|
|
146
|
-
console.log(result.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
147
|
-
// ['doc rdf:type http://example.org/Published', 'doc http://example.org/version 2.0']
|
|
148
|
-
console.log(result.remove.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
149
|
-
// ['doc rdf:type http://example.org/Draft', 'doc http://example.org/version Document']
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
### 6. External Retract (No Matching Positive)
|
|
153
|
-
|
|
154
|
-
When removing non-existent triples, they become external retractions:
|
|
155
|
-
|
|
156
|
-
```markdown
|
|
157
|
-
[ex] <http://example.org/>
|
|
158
|
-
|
|
159
|
-
# Document {=ex:doc}
|
|
160
|
-
|
|
161
|
-
[Alice] {-author} // External retract (no matching positive)
|
|
162
|
-
[Bob] {author} // Add Bob as author
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
**Result:**
|
|
166
|
-
```javascript
|
|
167
|
-
const result = parse({ text: markdown });
|
|
168
|
-
console.log(result.quads.map(q => `${q.object.value} ${q.predicate.value}`));
|
|
169
|
-
// ['Bob http://www.w3.org/2000/01/rdf-schema#author']
|
|
170
|
-
console.log(result.remove.map(q => `${q.object.value} ${q.predicate.value}`));
|
|
171
|
-
// ['Alice http://www.w3.org/2000/01/rdf-schema#author']
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
## Real-World Workflows
|
|
175
|
-
|
|
176
|
-
### 1. Document Versioning
|
|
177
|
-
|
|
178
|
-
Track changes across document versions:
|
|
179
|
-
|
|
180
|
-
```markdown
|
|
181
|
-
[ex] <http://example.org/>
|
|
182
|
-
|
|
183
|
-
# Article v1 {=ex:article .ex:Article}
|
|
184
|
-
[Alice] {author}
|
|
185
|
-
[Draft] {status}
|
|
186
|
-
|
|
187
|
-
# Article v2 {=ex:article}
|
|
188
|
-
[Alice] {-author} // Retract original author
|
|
189
|
-
[Bob] {author} // Add new author
|
|
190
|
-
[Draft] {-status} // Retract draft status
|
|
191
|
-
[Published] {status} // Add published status
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
**Merge Result:**
|
|
195
|
-
```javascript
|
|
196
|
-
const merged = merge([v1, v2]);
|
|
197
|
-
console.log(merged.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
198
|
-
// ['article rdf:type Article', 'article author Bob', 'article status Published']
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
### 2. Collaborative Editing
|
|
202
|
-
|
|
203
|
-
Multiple authors working simultaneously:
|
|
204
|
-
|
|
205
|
-
```markdown
|
|
206
|
-
[ex] <http://example.org/>
|
|
207
|
-
|
|
208
|
-
# Alice's changes
|
|
209
|
-
# Document {=ex:doc}
|
|
210
|
-
> Content A {section}
|
|
211
|
-
[Shared] {author}
|
|
212
|
-
|
|
213
|
-
# Bob's changes
|
|
214
|
-
# Document {=ex:doc}
|
|
215
|
-
> Content A {-section} // Retract Alice's content
|
|
216
|
-
> Content B {section} // Add Bob's content
|
|
217
|
-
[Shared] {-author} // Retract Alice's authorship
|
|
218
|
-
[Bob] {author} // Add himself as author
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
**Merge Result:**
|
|
222
|
-
```javascript
|
|
223
|
-
const merged = merge([aliceDoc, bobDoc]);
|
|
224
|
-
console.log(merged.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
225
|
-
// ['doc section Content B', 'doc author Bob']
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
### 3. Type Migration
|
|
229
|
-
|
|
230
|
-
Migrate data structures with controlled transitions:
|
|
231
|
-
|
|
232
|
-
```markdown
|
|
233
|
-
[ex] <http://example.org/>
|
|
234
|
-
|
|
235
|
-
# Old Schema
|
|
236
|
-
# Person {=ex:person .ex:Person}
|
|
237
|
-
[Alice] {name}
|
|
238
|
-
|
|
239
|
-
# New Schema
|
|
240
|
-
# Person {=ex:person -.ex:Person .ex:Human}
|
|
241
|
-
[Alice] {-name} // Retract old property
|
|
242
|
-
[Alice] {fullName} // Add new property
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
**Merge Result:**
|
|
246
|
-
```javascript
|
|
247
|
-
const migrated = merge([oldSchema, newSchema]);
|
|
248
|
-
console.log(migrated.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
249
|
-
// ['person rdf:type Human', 'person fullName Alice']
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
### 4. Environment Configuration
|
|
253
|
-
|
|
254
|
-
Manage environment-specific settings:
|
|
255
|
-
|
|
256
|
-
```markdown
|
|
257
|
-
[ex] <http://example.org/>
|
|
258
|
-
|
|
259
|
-
# Config {=ex:config}
|
|
260
|
-
|
|
261
|
-
# Development
|
|
262
|
-
[Debug Mode] {setting}
|
|
263
|
-
[localhost] {server}
|
|
264
|
-
|
|
265
|
-
# Production
|
|
266
|
-
[Debug Mode] {-setting} // Retract debug setting
|
|
267
|
-
[localhost] {-server} // Retract dev server
|
|
268
|
-
[prod.example.com] {server} // Add prod server
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
**Merge Result:**
|
|
272
|
-
```javascript
|
|
273
|
-
const configMerged = merge([devConfig, prodConfig]);
|
|
274
|
-
console.log(configMerged.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
275
|
-
// ['config server prod.example.com']
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
### 5. Template Instantiation
|
|
279
|
-
|
|
280
|
-
Use templates with placeholder content:
|
|
281
|
-
|
|
282
|
-
```markdown
|
|
283
|
-
[ex] <http://example.org/>
|
|
284
|
-
|
|
285
|
-
# Template {=ex:template}
|
|
286
|
-
[Placeholder] {title} // Template placeholder
|
|
287
|
-
[Draft] {status}
|
|
288
|
-
|
|
289
|
-
# Instance {=ex:instance}
|
|
290
|
-
[Placeholder] {-title} // Retract placeholder
|
|
291
|
-
[Real Title] {title} // Add real title
|
|
292
|
-
[Draft] {-status} // Retract draft status
|
|
293
|
-
[Published] {status} // Add published status
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
**Merge Result:**
|
|
297
|
-
```javascript
|
|
298
|
-
const instance = merge([template, instance]);
|
|
299
|
-
console.log(instance.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
300
|
-
// ['instance title Real Title', 'instance status Published']
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
### 6. Data Cleanup
|
|
304
|
-
|
|
305
|
-
Clean up inconsistent data:
|
|
306
|
-
|
|
307
|
-
```markdown
|
|
308
|
-
[ex] <http://example.org/>
|
|
309
|
-
|
|
310
|
-
# Messy Data {=ex:data}
|
|
311
|
-
[Alice] {name}
|
|
312
|
-
[alice] {name} // Duplicate with different case
|
|
313
|
-
[25] {age ^^xsd:integer}
|
|
314
|
-
[25] {age ^^xsd:string} // Wrong datatype
|
|
315
|
-
|
|
316
|
-
# Cleaned Data {=ex:data}
|
|
317
|
-
[alice] {-name} // Remove lowercase version
|
|
318
|
-
[25] {-age ^^xsd:string} // Remove wrong datatype
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
**Merge Result:**
|
|
322
|
-
```javascript
|
|
323
|
-
const cleaned = merge([messyData, cleanedData]);
|
|
324
|
-
console.log(cleaned.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value}`));
|
|
325
|
-
// ['data name Alice', 'data age 25^^xsd:integer']
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
## Advanced Patterns
|
|
329
|
-
|
|
330
|
-
### 1. Chained Retractions
|
|
331
|
-
|
|
332
|
-
Build retraction chains for complex changes:
|
|
333
|
-
|
|
334
|
-
```markdown
|
|
335
|
-
[ex] <http://example.org/>
|
|
336
|
-
|
|
337
|
-
# Article {=ex:article}
|
|
338
|
-
|
|
339
|
-
[Version 1] {title}
|
|
340
|
-
[Version 2] {title}
|
|
341
|
-
[Version 1] {-title} // Remove V1
|
|
342
|
-
[Version 3] {title}
|
|
343
|
-
[Version 2] {-title} // Remove V2
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
**Result:**
|
|
347
|
-
```javascript
|
|
348
|
-
const result = parse({ text: markdown });
|
|
349
|
-
console.log(result.quads.map(q => `${q.object.value} ${q.predicate.value}`));
|
|
350
|
-
// ['Version 3 http://www.w3.org/2000/01/rdf-schema#title']
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
### 2. Family Tree Management
|
|
354
|
-
|
|
355
|
-
Use reverse properties for family relationships:
|
|
356
|
-
|
|
357
|
-
```markdown
|
|
358
|
-
[ex] <http://example.org/>
|
|
359
|
-
|
|
360
|
-
# Family Tree
|
|
361
|
-
|
|
362
|
-
Parent: [John] {=ex:john .ex:Person}
|
|
363
|
-
Child: [Alice] {+ex:alice !ex:hasParent}
|
|
364
|
-
Child: [Bob] {+ex:bob !ex:hasParent}
|
|
365
|
-
|
|
366
|
-
# Update relationships
|
|
367
|
-
[Alice] {+ex:alice -!ex:hasParent} // Remove Alice's parent link
|
|
368
|
-
[Bob] {+ex:bob -!ex:hasParent} // Remove Bob's parent link
|
|
369
|
-
[Grandparent] {+ex:grandparent !ex:hasParent} // Add grandparent
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
**Result:**
|
|
373
|
-
```javascript
|
|
374
|
-
const result = parse({ text: markdown });
|
|
375
|
-
console.log(result.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value.split('/').pop()}`));
|
|
376
|
-
// ['john rdf:type Person', 'grandparent hasParent john']
|
|
377
|
-
```
|
|
378
|
-
|
|
379
|
-
### 3. Organizational Structure
|
|
380
|
-
|
|
381
|
-
Model company hierarchies with reverse properties:
|
|
382
|
-
|
|
383
|
-
```markdown
|
|
384
|
-
[org] <http://company.com/>
|
|
385
|
-
|
|
386
|
-
# Company Structure {=org:company}
|
|
387
|
-
|
|
388
|
-
CEO: [Jane] {+org:jane .org:Person}
|
|
389
|
-
Department: [Engineering] {+org:engineering !org:hasDepartment}
|
|
390
|
-
Team: [Platform] {+org:platform !org:hasTeam}
|
|
391
|
-
|
|
392
|
-
# Reorganization {=org:company}
|
|
393
|
-
[Engineering] {+org:engineering -!org:hasDepartment} // Remove department link
|
|
394
|
-
[Platform] {+org:platform -!org:hasTeam} // Remove team link
|
|
395
|
-
[Research] {+org:research !org:hasDepartment} // New department
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
**Result:**
|
|
399
|
-
```javascript
|
|
400
|
-
const result = parse({ text: markdown });
|
|
401
|
-
console.log(result.quads.map(q => `${q.subject.value.split('/').pop()} ${q.predicate.value} ${q.object.value.split('/').pop()}`));
|
|
402
|
-
// ['jane rdf:type Person', 'research hasDepartment jane']
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
## Remove Quads System
|
|
406
|
-
|
|
407
|
-
The parser maintains two separate collections:
|
|
408
|
-
|
|
409
|
-
- **`quads`** - Final resolved graph state (what actually exists)
|
|
410
|
-
- **`remove`** - External retractions targeting prior document state
|
|
411
|
-
|
|
412
|
-
### Intra-Document Cancel
|
|
413
|
-
|
|
414
|
-
When positive and negative triples match exactly within the same document:
|
|
415
|
-
|
|
416
|
-
```markdown
|
|
417
|
-
[ex] <http://example.org/>
|
|
418
|
-
|
|
419
|
-
# Employee {=my:emp456 .my:Employee}
|
|
420
|
-
[Software Engineer] {my:jobTitle}
|
|
421
|
-
[Software Engineer] {-my:jobTitle} // Cancels above
|
|
422
|
-
[Senior Software Engineer] {my:jobTitle}
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
**Result:**
|
|
426
|
-
```javascript
|
|
427
|
-
const result = parse({ text: markdown });
|
|
428
|
-
console.log(result.quads.length); // 2 (type + final jobTitle)
|
|
429
|
-
console.log(result.remove.length); // 0 (empty - no external retractions)
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
### External Retract
|
|
433
|
-
|
|
434
|
-
When negative triples don't find matching positives in the current document:
|
|
435
|
-
|
|
436
|
-
```markdown
|
|
437
|
-
[ex] <http://example.org/>
|
|
438
|
-
|
|
439
|
-
# Employee {=my:emp456}
|
|
440
|
-
[Software Engineer] {-my:jobTitle} // No matching positive in current doc
|
|
441
|
-
[Senior Software Engineer] {my:jobTitle}
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
**Result:**
|
|
445
|
-
```javascript
|
|
446
|
-
const result = parse({ text: markdown });
|
|
447
|
-
console.log(result.quads.length); // 2 (type + Senior Software Engineer)
|
|
448
|
-
console.log(result.remove.length); // 1 (Software Engineer retract)
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
### Merge Resolution
|
|
452
|
-
|
|
453
|
-
External retractions are resolved during document merging:
|
|
454
|
-
|
|
455
|
-
```javascript
|
|
456
|
-
import { merge } from 'mdld-parse';
|
|
457
|
-
|
|
458
|
-
const doc1 = `
|
|
459
|
-
[my] <tag:ex,2026:>
|
|
460
|
-
# Employee {=my:emp456 .my:Employee}
|
|
461
|
-
[Software Engineer] {my:jobTitle}`;
|
|
462
|
-
|
|
463
|
-
const doc2 = `
|
|
464
|
-
[my] <tag:ex,2026:>
|
|
465
|
-
# Employee {=my:emp456}
|
|
466
|
-
[Software Engineer] {-my:jobTitle} // External retract
|
|
467
|
-
[Senior Software Engineer] {my:jobTitle}`;
|
|
468
|
-
|
|
469
|
-
const merged = merge([doc1, doc2]);
|
|
470
|
-
console.log(merged.quads); // Software Engineer removed, Senior Software Engineer remains
|
|
471
|
-
console.log(merged.remove); // [] - Empty after resolution
|
|
472
|
-
```
|
|
473
|
-
|
|
474
|
-
### Hard Invariant
|
|
475
|
-
|
|
476
|
-
The system maintains the hard invariant: **quads ∩ remove = ∅**
|
|
477
|
-
|
|
478
|
-
```javascript
|
|
479
|
-
const result = parse({ text: markdown });
|
|
480
|
-
|
|
481
|
-
// This is always true:
|
|
482
|
-
const overlap = result.quads.some(quad =>
|
|
483
|
-
result.remove.some(remove =>
|
|
484
|
-
quad.subject.equals(remove.subject) &&
|
|
485
|
-
quad.predicate.equals(remove.predicate) &&
|
|
486
|
-
quad.object.equals(remove.object)
|
|
487
|
-
)
|
|
488
|
-
);
|
|
489
|
-
|
|
490
|
-
console.log(overlap); // false - never any overlap
|
|
491
|
-
```
|
|
492
|
-
|
|
493
|
-
## Use Cases for Polarity
|
|
494
|
-
|
|
495
|
-
### 1. Document Versioning
|
|
496
|
-
```javascript
|
|
497
|
-
// v1: Original document
|
|
498
|
-
const v1 = parse(`[ex] <tag:ex,2026:>
|
|
499
|
-
|
|
500
|
-
# Article {=ex:article}
|
|
501
|
-
[Alice] {author}`);
|
|
502
|
-
|
|
503
|
-
// v2: Update with retraction
|
|
504
|
-
const v2 = parse(`
|
|
505
|
-
[ex] <tag:ex,2026:>
|
|
506
|
-
# Article {=ex:article}
|
|
507
|
-
[Alice] {-author} // External retract
|
|
508
|
-
[Bob] {author}`);
|
|
509
|
-
|
|
510
|
-
// Merge to get final state
|
|
511
|
-
const final = merge([v1, v2]);
|
|
512
|
-
// Result: Bob is author, Alice removed
|
|
513
|
-
```
|
|
514
|
-
|
|
515
|
-
### 2. Collaborative Editing
|
|
516
|
-
```javascript
|
|
517
|
-
// Alice's changes
|
|
518
|
-
const alice = parse(`# Doc {=ex:doc}
|
|
519
|
-
> Content A {section}`);
|
|
520
|
-
|
|
521
|
-
// Bob's changes (retract Alice's content)
|
|
522
|
-
const bob = parse(`# Doc {=ex:doc}
|
|
523
|
-
> Content A {-section} // External retract
|
|
524
|
-
> Content B {section}`);
|
|
525
|
-
|
|
526
|
-
// Resolve conflicts
|
|
527
|
-
const resolved = merge([alice, bob]);
|
|
528
|
-
// Result: Only Content B remains
|
|
529
|
-
```
|
|
530
|
-
|
|
531
|
-
### 3. Data Migration
|
|
532
|
-
```javascript
|
|
533
|
-
// Old schema
|
|
534
|
-
const old = parse(`
|
|
535
|
-
[ex] <tag:ex,2026:>
|
|
536
|
-
# Person {=ex:person}
|
|
537
|
-
[Employee] {ex:status}`);
|
|
538
|
-
|
|
539
|
-
// Migration script
|
|
540
|
-
const migration = parse(`
|
|
541
|
-
[ex] <tag:ex,2026:>
|
|
542
|
-
# Person {=ex:person}
|
|
543
|
-
[Employee] {-ex:status} // Retract old status
|
|
544
|
-
[Staff] {ex:status} // Add new status`);
|
|
545
|
-
|
|
546
|
-
const migrated = merge([old, migration]);
|
|
547
|
-
// Result: Status changed from Employee to Staff
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
## Performance Characteristics
|
|
551
|
-
|
|
552
|
-
- **O(1) lookup:** Quad keys enable fast cancel/retract detection
|
|
553
|
-
- **Streaming:** Remove detection during single-pass parsing
|
|
554
|
-
- **Memory efficient:** Remove quads stored separately from final state
|
|
555
|
-
- **Deterministic:** Same input always produces same quads/remove separation
|
|
556
|
-
|
|
557
|
-
## API Reference
|
|
558
|
-
|
|
559
|
-
```javascript
|
|
560
|
-
const result = parse({ text: markdown, context, dataFactory, graph });
|
|
561
|
-
|
|
562
|
-
// Final resolved graph state
|
|
563
|
-
console.log(result.quads); // Array of RDF/JS Quads
|
|
564
|
-
console.log(result.remove); // Array of RDF/JS Quads (external retractions only)
|
|
565
|
-
console.log(result.origin); // Lean origin tracking for UI navigation
|
|
566
|
-
|
|
567
|
-
// Origin tracking includes polarity info
|
|
568
|
-
const location = locate(quad, result.origin);
|
|
569
|
-
console.log(location.polarity); // '+' for quads, '-' for removes
|
|
570
|
-
```
|
|
571
|
-
|
|
572
|
-
## Best Practices
|
|
573
|
-
|
|
574
|
-
1. **Use external retractions for versioning** - Retract old versions in new documents
|
|
575
|
-
2. **Combine retractions in single annotation** - Batch related changes together
|
|
576
|
-
3. **Test merge behavior** - Verify that retractions work as expected
|
|
577
|
-
4. **Document intent** - Explain why retractions are needed
|
|
578
|
-
5. **Use type migration** - Change data structures safely with type retractions
|
|
579
|
-
6. **Ensure proper context** - Reverse properties need subject and object declarations
|
|
580
|
-
|
|
581
|
-
## Limitations
|
|
582
|
-
|
|
583
|
-
- **Exact SPO matching** - Only exact subject-predicate-object triples cancel
|
|
584
|
-
- **No partial retractions** - Can't retract based on patterns or conditions
|
|
585
|
-
- **Forward-reference constraint** - Retractions must reference previously declared items
|
|
586
|
-
- **Context requirements** - Reverse properties need proper subject context and object declarations
|