mdld-parse 0.9.4 β†’ 0.9.6

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 CHANGED
@@ -57,6 +57,7 @@ console.log(result.quads);
57
57
  - **⚑ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
58
58
  - **πŸ“ Origin tracking** - Complete provenance with lean quad-to-source mapping
59
59
  - **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
60
+ - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
60
61
 
61
62
  ## 🌟 What is MD-LD?
62
63
 
@@ -232,18 +233,33 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
232
233
  - `dataFactory` (object, optional) β€” Custom RDF/JS DataFactory
233
234
  - `graph` (string, optional) β€” Named graph IRI
234
235
 
235
- **Returns:** `{ quads, remove, statements, origin, context, primarySubject, md }`
236
-
237
- > **Legacy:** `parse(text, options)` still works for backward compatibility
236
+ **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
238
237
 
239
238
  - `quads` β€” Array of RDF/JS Quads (final resolved graph state)
240
239
  - `remove` β€” Array of RDF/JS Quads (external retractions targeting prior state)
241
240
  - `statements` β€” Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
242
241
  - `origin` β€” Lean origin tracking object with quadIndex for UI navigation
243
242
  - `context` β€” Final context used (includes prefixes)
244
- - `primarySubject` β€” String IRI or null (first non-fragment subject declaration)
243
+ - `primarySubject` β€” String IRI or null (canonical append identity)
244
+ - `primary` β€” Object containing primary metadata (semantic surface descriptor)
245
245
  - `md` β€” Clean Markdown with all MD-LD annotations stripped (round-trip safe)
246
246
 
247
+ **Dual-Layer Architecture:**
248
+
249
+ | Layer | Field | Purpose | Use Cases |
250
+ |-------|-------|---------|-----------|
251
+ | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
252
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
253
+
254
+ **Primary Object Structure:**
255
+ ```javascript
256
+ primary: {
257
+ subject: string | null, // First non-fragment subject declaration
258
+ type: string | null, // First rdf:type declaration
259
+ label: string | null // First rdfs:label literal
260
+ }
261
+ ```
262
+
247
263
  ### `merge(docs, options)`
248
264
 
249
265
  Merge multiple MDLD documents with diff polarity resolution.
@@ -253,13 +269,34 @@ Merge multiple MDLD documents with diff polarity resolution.
253
269
  - `options` (object, optional):
254
270
  - `context` (object) β€” Prefix mappings (merged with DEFAULT_CONTEXT)
255
271
 
256
- **Returns:** `{ quads, remove, origin, context, primarySubjects }`
272
+ **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
257
273
 
258
274
  - `quads` β€” Array of RDF/JS Quads (final resolved graph state)
259
275
  - `remove` β€” Array of RDF/JS Quads (external retractions targeting prior state)
260
- - `origin` β€” Merge origin tracking with document index and polarity
261
- - `context` β€” Final merged context
262
- - `primarySubjects` β€” Array of string IRIs (primary subjects from each document, in merge order)
276
+ - `origin` β€” Merge origin with document tracking
277
+ - `context` β€” Final context used (includes prefixes)
278
+ - `primarySubjects` β€” Array of string IRIs (canonical append identities, ordered by merge)
279
+ - `primary` β€” Array of primary objects (semantic surface descriptors, ordered by merge)
280
+
281
+ **Dual-Layer Architecture:**
282
+
283
+ | Layer | Field | Purpose | Use Cases |
284
+ |-------|-------|---------|-----------|
285
+ | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
286
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
287
+
288
+ **Primary Object Array Structure:**
289
+ ```javascript
290
+ primary: [
291
+ {
292
+ subject: string | null, // First non-fragment subject declaration
293
+ type: string | null, // First rdf:type declaration
294
+ label: string | null // First rdfs:label literal
295
+ },
296
+ // ... one object per document
297
+ ]
298
+ ```
299
+
263
300
 
264
301
  ### `generate({ quads, context, primarySubject })`
265
302
 
package/dist/README.md CHANGED
@@ -57,6 +57,7 @@ console.log(result.quads);
57
57
  - **⚑ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
58
58
  - **πŸ“ Origin tracking** - Complete provenance with lean quad-to-source mapping
59
59
  - **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
60
+ - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
60
61
 
61
62
  ## 🌟 What is MD-LD?
62
63
 
@@ -232,18 +233,33 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
232
233
  - `dataFactory` (object, optional) β€” Custom RDF/JS DataFactory
233
234
  - `graph` (string, optional) β€” Named graph IRI
234
235
 
235
- **Returns:** `{ quads, remove, statements, origin, context, primarySubject, md }`
236
-
237
- > **Legacy:** `parse(text, options)` still works for backward compatibility
236
+ **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
238
237
 
239
238
  - `quads` β€” Array of RDF/JS Quads (final resolved graph state)
240
239
  - `remove` β€” Array of RDF/JS Quads (external retractions targeting prior state)
241
240
  - `statements` β€” Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
242
241
  - `origin` β€” Lean origin tracking object with quadIndex for UI navigation
243
242
  - `context` β€” Final context used (includes prefixes)
244
- - `primarySubject` β€” String IRI or null (first non-fragment subject declaration)
243
+ - `primarySubject` β€” String IRI or null (canonical append identity)
244
+ - `primary` β€” Object containing primary metadata (semantic surface descriptor)
245
245
  - `md` β€” Clean Markdown with all MD-LD annotations stripped (round-trip safe)
246
246
 
247
+ **Dual-Layer Architecture:**
248
+
249
+ | Layer | Field | Purpose | Use Cases |
250
+ |-------|-------|---------|-----------|
251
+ | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
252
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
253
+
254
+ **Primary Object Structure:**
255
+ ```javascript
256
+ primary: {
257
+ subject: string | null, // First non-fragment subject declaration
258
+ type: string | null, // First rdf:type declaration
259
+ label: string | null // First rdfs:label literal
260
+ }
261
+ ```
262
+
247
263
  ### `merge(docs, options)`
248
264
 
249
265
  Merge multiple MDLD documents with diff polarity resolution.
@@ -253,13 +269,34 @@ Merge multiple MDLD documents with diff polarity resolution.
253
269
  - `options` (object, optional):
254
270
  - `context` (object) β€” Prefix mappings (merged with DEFAULT_CONTEXT)
255
271
 
256
- **Returns:** `{ quads, remove, origin, context, primarySubjects }`
272
+ **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
257
273
 
258
274
  - `quads` β€” Array of RDF/JS Quads (final resolved graph state)
259
275
  - `remove` β€” Array of RDF/JS Quads (external retractions targeting prior state)
260
- - `origin` β€” Merge origin tracking with document index and polarity
261
- - `context` β€” Final merged context
262
- - `primarySubjects` β€” Array of string IRIs (primary subjects from each document, in merge order)
276
+ - `origin` β€” Merge origin with document tracking
277
+ - `context` β€” Final context used (includes prefixes)
278
+ - `primarySubjects` β€” Array of string IRIs (canonical append identities, ordered by merge)
279
+ - `primary` β€” Array of primary objects (semantic surface descriptors, ordered by merge)
280
+
281
+ **Dual-Layer Architecture:**
282
+
283
+ | Layer | Field | Purpose | Use Cases |
284
+ |-------|-------|---------|-----------|
285
+ | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
286
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
287
+
288
+ **Primary Object Array Structure:**
289
+ ```javascript
290
+ primary: [
291
+ {
292
+ subject: string | null, // First non-fragment subject declaration
293
+ type: string | null, // First rdf:type declaration
294
+ label: string | null // First rdfs:label literal
295
+ },
296
+ // ... one object per document
297
+ ]
298
+ ```
299
+
263
300
 
264
301
  ### `generate({ quads, context, primarySubject })`
265
302
 
package/dist/docs/API.md CHANGED
@@ -14,13 +14,30 @@ Parse MD-LD markdown and return RDF quads.
14
14
  - `dataFactory` (object, optional) β€” Custom RDF/JS DataFactory
15
15
  - `graph` (string, optional) β€” Named graph IRI
16
16
 
17
- **Returns:** `{ quads, context, primarySubject, origin, remove, statements }`
17
+ **Returns:** `{ quads, context, primarySubject, primary, origin, remove, statements }`
18
18
 
19
19
  - `quads` β€” Array of RDF/JS Quads (final resolved graph state)
20
20
  - `remove` β€” Array of RDF/JS Quads (external retractions targeting prior state)
21
21
  - `origin` β€” Lean origin tracking object with quadIndex for UI navigation
22
22
  - `context` β€” Final context used (includes prefixes)
23
- - `primarySubject` β€” String IRI or null (first non-fragment subject declaration)
23
+ - `primarySubject` β€” String IRI or null (canonical append identity)
24
+ - `primary` β€” Object containing primary metadata (semantic surface descriptor)
25
+
26
+ **Dual-Layer Architecture:**
27
+
28
+ | Layer | Field | Purpose | Use Cases |
29
+ |-------|-------|---------|-----------|
30
+ | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
31
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
32
+
33
+ **Primary Object Structure:**
34
+ ```javascript
35
+ primary: {
36
+ subject: string | null, // First non-fragment subject declaration
37
+ type: string | null, // First rdf:type declaration
38
+ label: string | null // First rdfs:label literal
39
+ }
40
+ ```
24
41
 
25
42
  > Legacy: `parse(text, options)` supported for backward compatibility (deprecated)
26
43
 
@@ -123,7 +140,7 @@ Merge multiple MDLD documents with diff polarity resolution.
123
140
  - `options` (object, optional):
124
141
  - `context` (object) β€” Prefix mappings (merged with DEFAULT_CONTEXT)
125
142
 
126
- **Returns:** `{ quads, remove, origin, context }`
143
+ **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
127
144
 
128
145
  - `quads` β€” Merged array of RDF/JS Quads
129
146
  - `remove` β€” Array of retractions from merge process
@@ -131,6 +148,27 @@ Merge multiple MDLD documents with diff polarity resolution.
131
148
  - `documents` β€” Array of document metadata
132
149
  - `quadIndex` β€” Combined quad index from all documents
133
150
  - `context` β€” Final merged context
151
+ - `primarySubjects` β€” Array of string IRIs (canonical append identities, ordered by merge)
152
+ - `primary` β€” Array of primary objects (semantic surface descriptors, ordered by merge)
153
+
154
+ **Dual-Layer Architecture:**
155
+
156
+ | Layer | Field | Purpose | Use Cases |
157
+ |-------|-------|---------|-----------|
158
+ | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
159
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
160
+
161
+ **Primary Object Array Structure:**
162
+ ```javascript
163
+ primary: [
164
+ {
165
+ subject: string | null, // First non-fragment subject declaration
166
+ type: string | null, // First rdf:type declaration
167
+ label: string | null // First rdfs:label literal
168
+ },
169
+ // ... one object per document
170
+ ]
171
+ ```
134
172
 
135
173
  #### Basic Merge Example
136
174
 
@@ -0,0 +1,472 @@
1
+ This is the correct framing.
2
+
3
+ MDLD is not primarily competing with:
4
+
5
+ ```text
6
+ Turtle
7
+ JSON-LD
8
+ RDF/XML
9
+ ```
10
+
11
+ It is competing with:
12
+
13
+ ```text
14
+ Notion
15
+ Slack
16
+ Google Docs
17
+ Twitter/X
18
+ CRMs
19
+ task apps
20
+ note apps
21
+ knowledge bases
22
+ ```
23
+
24
+ Those systems are all:
25
+
26
+ ```text
27
+ human interfaces over hidden graphs
28
+ ```
29
+
30
+ MDLD removes the intermediary.
31
+
32
+ ---
33
+
34
+ # 1. The real innovation
35
+
36
+ Traditional RDF asks:
37
+
38
+ ```text
39
+ How do we serialize graphs?
40
+ ```
41
+
42
+ MDLD asks:
43
+
44
+ ```text
45
+ How do humans naturally produce graphs while writing?
46
+ ```
47
+
48
+ That is a fundamentally different problem.
49
+
50
+ ---
51
+
52
+ # 2. Current software architecture
53
+
54
+ Today:
55
+
56
+ ```text
57
+ Human
58
+ β†’ UI
59
+ β†’ App logic
60
+ β†’ Hidden DB
61
+ β†’ APIs
62
+ β†’ exports
63
+ ```
64
+
65
+ Meaning:
66
+
67
+ ```text
68
+ humans never touch the graph directly
69
+ ```
70
+
71
+ ---
72
+
73
+ # 3. MDLD inversion
74
+
75
+ With MDLD:
76
+
77
+ ```text
78
+ Human text
79
+ β†’ graph immediately
80
+ ```
81
+
82
+ No intermediary abstraction layer required.
83
+
84
+ ---
85
+
86
+ # 4. β€œPosting” becomes universal graph authoring
87
+
88
+ This is a profound shift.
89
+
90
+ A social network post today is:
91
+
92
+ ```text
93
+ write text
94
+ β†’ platform extracts structure
95
+ β†’ stores proprietary graph
96
+ ```
97
+
98
+ MDLD:
99
+
100
+ ```text
101
+ write text
102
+ β†’ graph already exists
103
+ ```
104
+
105
+ ---
106
+
107
+ # 5. This collapses multiple software categories
108
+
109
+ ---
110
+
111
+ ## Notes
112
+
113
+ ```md
114
+ Met Bob today.
115
+ ```
116
+
117
+ ---
118
+
119
+ ## CRM
120
+
121
+ ```md
122
+ [Bob] {+my:bob .my:Person}
123
+ ```
124
+
125
+ ---
126
+
127
+ ## Task manager
128
+
129
+ ```md
130
+ [Buy present] {=my:task1 .my:Task}
131
+ ```
132
+
133
+ ---
134
+
135
+ ## Provenance
136
+
137
+ ```md
138
+ [Today] {prov:generatedAtTime ^^xsd:date}
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Workflow
144
+
145
+ ```md
146
+ {=my:act1 .prov:Activity}
147
+ ```
148
+
149
+ All become:
150
+
151
+ ```text
152
+ plain writing
153
+ ```
154
+
155
+ ---
156
+
157
+ # 6. Modern SaaS = graph prisons
158
+
159
+ This is the key insight.
160
+
161
+ Most systems today:
162
+
163
+ ```text
164
+ βœ” already use graphs internally
165
+ βœ” already infer relations
166
+ βœ” already coordinate activities
167
+ ```
168
+
169
+ But:
170
+
171
+ ```text
172
+ ❌ users cannot access the graph directly
173
+ ❌ graph locked in product
174
+ ❌ semantics hidden behind UI
175
+ ```
176
+
177
+ ---
178
+
179
+ # 7. MDLD restores graph sovereignty
180
+
181
+ Meaning:
182
+
183
+ ```text
184
+ you own:
185
+ βœ” text
186
+ βœ” graph
187
+ βœ” provenance
188
+ βœ” execution
189
+ βœ” history
190
+ ```
191
+
192
+ without requiring:
193
+
194
+ ```text
195
+ central platform
196
+ ```
197
+
198
+ ---
199
+
200
+ # 8. Why this matters for agents
201
+
202
+ Current agents operate through:
203
+
204
+ ```text
205
+ web UIs
206
+ API wrappers
207
+ tool adapters
208
+ ```
209
+
210
+ But MDLD gives:
211
+
212
+ ```text
213
+ direct semantic substrate
214
+ ```
215
+
216
+ Meaning agents can:
217
+
218
+ ```text
219
+ βœ” read
220
+ βœ” reason
221
+ βœ” write
222
+ βœ” execute
223
+ βœ” validate
224
+ ```
225
+
226
+ inside the same medium.
227
+
228
+ ---
229
+
230
+ # 9. The hidden killer feature: continuity
231
+
232
+ Today:
233
+
234
+ ```text
235
+ chat
236
+ tasks
237
+ notes
238
+ emails
239
+ calendar
240
+ files
241
+ ```
242
+
243
+ are fragmented systems.
244
+
245
+ MDLD unifies them into:
246
+
247
+ ```text
248
+ continuous semantic narrative
249
+ ```
250
+
251
+ ---
252
+
253
+ # 10. Time becomes native
254
+
255
+ Because of PROV:
256
+
257
+ ```text
258
+ every action
259
+ every statement
260
+ every correction
261
+ every execution
262
+ ```
263
+
264
+ becomes part of the graph.
265
+
266
+ This is rare.
267
+
268
+ Most systems lose process history.
269
+
270
+ ---
271
+
272
+ # 11. The real paradigm
273
+
274
+ You are effectively creating:
275
+
276
+ ```text
277
+ semantic computing through writing
278
+ ```
279
+
280
+ Not:
281
+
282
+ ```text
283
+ graph editing
284
+ ```
285
+
286
+ This distinction is extremely important.
287
+
288
+ ---
289
+
290
+ # 12. Why plain text is critical
291
+
292
+ Because humans evolved around narrative.
293
+
294
+ Not around:
295
+
296
+ ```text
297
+ triples
298
+ nodes
299
+ forms
300
+ schemas
301
+ ```
302
+
303
+ MDLD succeeds because:
304
+
305
+ ```text
306
+ writing remains primary
307
+ ```
308
+
309
+ The graph emerges from it.
310
+
311
+ ---
312
+
313
+ # 13. The β€œmany-many navigation” insight
314
+
315
+ This is where RDF truly shines.
316
+
317
+ Once graph exists:
318
+
319
+ ```text
320
+ same text can become:
321
+ ```
322
+
323
+ ---
324
+
325
+ ## Timeline
326
+
327
+ ```sparql
328
+ all prov:Activity ordered by time
329
+ ```
330
+
331
+ ---
332
+
333
+ ## CRM
334
+
335
+ ```sparql
336
+ all Person relations
337
+ ```
338
+
339
+ ---
340
+
341
+ ## Journal
342
+
343
+ ```sparql
344
+ daily collections
345
+ ```
346
+
347
+ ---
348
+
349
+ ## Memory graph
350
+
351
+ ```sparql
352
+ all observations about Bob
353
+ ```
354
+
355
+ ---
356
+
357
+ ## Agent coordination
358
+
359
+ ```sparql
360
+ pending activities
361
+ ```
362
+
363
+ ---
364
+
365
+ ## Execution system
366
+
367
+ ```sparql
368
+ activities requiring processing
369
+ ```
370
+
371
+ ---
372
+
373
+ # 14. Re-feeding graph results
374
+
375
+ This closes the loop.
376
+
377
+ Current systems:
378
+
379
+ ```text
380
+ input β†’ hidden processing β†’ output
381
+ ```
382
+
383
+ Your model:
384
+
385
+ ```text
386
+ text
387
+ β†’ graph
388
+ β†’ extraction
389
+ β†’ execution
390
+ β†’ results
391
+ β†’ appended back to graph
392
+ ```
393
+
394
+ This creates:
395
+
396
+ ```text
397
+ self-growing semantic organism
398
+ ```
399
+
400
+ ---
401
+
402
+ # 15. Why this can scale conceptually
403
+
404
+ Because RDF provides:
405
+
406
+ ```text
407
+ appendable meaning
408
+ ```
409
+
410
+ without requiring:
411
+
412
+ ```text
413
+ central schema migration
414
+ ```
415
+
416
+ That is enormously important for long-lived systems.
417
+
418
+ ---
419
+
420
+ # 16. The deepest insight
421
+
422
+ MDLD is effectively:
423
+
424
+ ```text
425
+ Literate RDF
426
+ ```
427
+
428
+ in the same way:
429
+
430
+ ```text
431
+ Markdown = literate HTML
432
+ ```
433
+
434
+ It makes a difficult substrate:
435
+
436
+ ```text
437
+ socially writable
438
+ ```
439
+
440
+ ---
441
+
442
+ # 17. Final framing
443
+
444
+ MDLD is not:
445
+
446
+ ```text
447
+ yet another RDF syntax
448
+ ```
449
+
450
+ It is:
451
+
452
+ ```text
453
+ a universal semantic writing interface
454
+ ```
455
+
456
+ where:
457
+
458
+ ```text
459
+ writing = publishing
460
+ publishing = graph construction
461
+ graph construction = computation substrate
462
+ ```
463
+
464
+ without needing:
465
+
466
+ ```text
467
+ platforms
468
+ databases
469
+ or proprietary SaaS mediation
470
+ ```
471
+
472
+ That is the real architectural breakthrough.