mdld-parse 0.9.1 → 0.9.3

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 (59) hide show
  1. package/README.md +34 -1
  2. package/dist/.nojekyll +0 -0
  3. package/dist/CNAME +1 -0
  4. package/dist/README.md +425 -0
  5. package/dist/docs/API.md +397 -0
  6. package/dist/docs/Architecture.md +190 -0
  7. package/dist/docs/Guide.md +322 -0
  8. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  9. package/dist/docs/Parser.md +654 -0
  10. package/dist/docs/Performance.md +238 -0
  11. package/dist/docs/Spec-render.md +1439 -0
  12. package/dist/docs/Subject.md +180 -0
  13. package/dist/docs/Syntax.md +463 -0
  14. package/dist/docs/TodoList.md +215 -0
  15. package/dist/docs/Use-Cases.md +354 -0
  16. package/dist/docs/index.html +108 -0
  17. package/dist/docs/index.md +56 -0
  18. package/dist/docs/origin.md +459 -0
  19. package/dist/docs/polarity.md +586 -0
  20. package/dist/docs/primary-subject.md +199 -0
  21. package/dist/docs/statements.md +226 -0
  22. package/dist/docs/tokenization-performance-report.md +164 -0
  23. package/dist/examples/Cookbook.md +32 -0
  24. package/dist/examples/Status-SHACL.md +33 -0
  25. package/dist/examples/demo/index.md +35 -0
  26. package/dist/examples/demo/journal.md +18 -0
  27. package/dist/examples/demo/minimal.md +11 -0
  28. package/dist/examples/demo/project.md +15 -0
  29. package/dist/examples/demo/recipe.md +31 -0
  30. package/dist/examples/demo/research.md +46 -0
  31. package/dist/examples/demo/space-mission.md +48 -0
  32. package/dist/examples/dogfood.md +288 -0
  33. package/dist/examples/few-shot.md +309 -0
  34. package/dist/examples/graph/rdf-graph.html +473 -0
  35. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  36. package/dist/examples/index.md +45 -0
  37. package/dist/examples/llm-time-workflow.md +173 -0
  38. package/dist/examples/prov-o.md +2367 -0
  39. package/dist/examples/rdf.md +827 -0
  40. package/dist/examples/shacl.md +3399 -0
  41. package/dist/examples/statements.md +43 -0
  42. package/dist/examples/workflow.md +150 -0
  43. package/dist/index.html +2827 -0
  44. package/dist/index.js +1548 -0
  45. package/dist/logo.svg +7 -0
  46. package/dist/spec/Spec-compact.md +363 -0
  47. package/dist/spec/Spec-ultra.md +221 -0
  48. package/dist/spec/Spec.md +1068 -0
  49. package/dist/spec/index.md +46 -0
  50. package/package.json +13 -8
  51. package/src/constants.js +0 -31
  52. package/src/generate.js +0 -245
  53. package/src/index.js +0 -13
  54. package/src/locate.js +0 -23
  55. package/src/merge.js +0 -157
  56. package/src/parse.js +0 -765
  57. package/src/render.js +0 -576
  58. package/src/shared.js +0 -577
  59. package/src/utils.js +0 -430
@@ -0,0 +1,586 @@
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