mdld-parse 0.9.5 → 0.9.8

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,45 +57,12 @@ 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** - Instant access to primarySubject, primaryType, and primaryLabel for document identity
60
+ - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
61
61
 
62
62
  ## 🌟 What is MD-LD?
63
63
 
64
64
  MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
65
65
 
66
- ## ⚡ Performance & Architecture
67
-
68
- MD-LD v0.10.0 features a **character-based tokenization system** for optimal performance:
69
-
70
- - **20-28% faster parsing** than regex-based approaches
71
- - **Memory-efficient** with ~640 bytes per quad retained
72
- - **Streaming-friendly** with O(n) linear time complexity
73
- - **Character-based detection** replaces complex regex patterns
74
- - **Unified tokenizer architecture** in `src/tokenizers.js`
75
-
76
- ### Tokenizer Architecture
77
-
78
- The parser uses specialized character-based tokenizers:
79
-
80
- ```javascript
81
- // Block-level tokenizers
82
- detectFence() // ```code blocks
83
- detectPrefix() // [prefix] <iri>
84
- detectHeading() // # Headings
85
- detectList() // - List items
86
- detectBlockquote() // > Blockquotes
87
- detectStandaloneSubject() // {=subject}
88
-
89
- // Inline carrier scanner
90
- scanInlineCarriers() // [text], **bold**, `code`, <URL>
91
- ```
92
-
93
- This design provides:
94
- - **Better maintainability** - Easier to debug and extend
95
- - **Improved error handling** - More precise edge case detection
96
- - **Cleaner code structure** - No complex regex patterns
97
- - **Full backward compatibility** - All 127 tests passing
98
-
99
66
  ```markdown
100
67
  [my] <tag:alice@example.com,2026:>
101
68
  # 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
@@ -118,13 +85,15 @@ pnpm install mdld-parse
118
85
  ```javascript
119
86
  import { parse } from 'mdld-parse';
120
87
 
121
- const markdown = `# Document {=ex:doc .Article}
122
- [Alice] {author}`;
88
+ const markdown = `[ex] <tag:alice@example.org,2026:>
123
89
 
124
- const result = parse({
125
- text: markdown,
126
- context: { ex: 'http://example.org/' }
127
- });
90
+ # Demo document {=ex:example/doc .prov:Entity label}
91
+
92
+ > A demo document for MD-LD {comment}
93
+ [Alice] {+ex:alice ?ex:author .prov:Person label}
94
+ `;
95
+
96
+ const result = parse({ text: markdown });
128
97
 
129
98
  console.log(result.quads);
130
99
  // RDF/JS quads ready for n3.js, rdflib, etc.
@@ -136,7 +105,7 @@ console.log(result.quads);
136
105
  <script type="module">
137
106
  import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
138
107
 
139
- const result = parse('# Hello {=ex:hello label}');
108
+ const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
140
109
  </script>
141
110
  ```
142
111
 
@@ -154,9 +123,9 @@ Each predicate form determines the graph edge:
154
123
 
155
124
  | Form | Edge | Example | Meaning |
156
125
  |-------|---------|------------------------------|------------------|
157
- | `p` | S → L | `[Alice] {name}` | literal property |
126
+ | `p` | S → L | `[Alice] {label}` | literal property |
158
127
  | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
159
- | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
128
+ | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
160
129
 
161
130
  ## 📍 Elevated Statements
162
131
 
@@ -233,18 +202,33 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
233
202
  - `dataFactory` (object, optional) — Custom RDF/JS DataFactory
234
203
  - `graph` (string, optional) — Named graph IRI
235
204
 
236
- **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primaryType, primaryLabel, md }`
205
+ **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
237
206
 
238
207
  - `quads` — Array of RDF/JS Quads (final resolved graph state)
239
208
  - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
240
209
  - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
241
210
  - `origin` — Lean origin tracking object with quadIndex for UI navigation
242
211
  - `context` — Final context used (includes prefixes)
243
- - `primarySubject` — String IRI or null (first non-fragment subject declaration)
244
- - `primaryType` — String IRI or null (first rdf:type declaration)
245
- - `primaryLabel` — String or null (first rdfs:label literal)
212
+ - `primarySubject` — String IRI or null (canonical append identity)
213
+ - `primary` — Object containing primary metadata (semantic surface descriptor)
246
214
  - `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
247
215
 
216
+ **Dual-Layer Architecture:**
217
+
218
+ | Layer | Field | Purpose | Use Cases |
219
+ |-------|-------|---------|-----------|
220
+ | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
221
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
222
+
223
+ **Primary Object Structure:**
224
+ ```javascript
225
+ primary: {
226
+ subject: string | null, // First non-fragment subject declaration
227
+ type: string | null, // First rdf:type declaration
228
+ label: string | null // First rdfs:label literal
229
+ }
230
+ ```
231
+
248
232
  ### `merge(docs, options)`
249
233
 
250
234
  Merge multiple MDLD documents with diff polarity resolution.
@@ -254,13 +238,34 @@ Merge multiple MDLD documents with diff polarity resolution.
254
238
  - `options` (object, optional):
255
239
  - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
256
240
 
257
- **Returns:** `{ quads, remove, origin, context, primarySubjects }`
241
+ **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
258
242
 
259
243
  - `quads` — Array of RDF/JS Quads (final resolved graph state)
260
244
  - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
261
- - `origin` — Merge origin tracking with document index and polarity
262
- - `context` — Final merged context
263
- - `primarySubjects` — Array of string IRIs (primary subjects from each document, in merge order)
245
+ - `origin` — Merge origin with document tracking
246
+ - `context` — Final context used (includes prefixes)
247
+ - `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
248
+ - `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
249
+
250
+ **Dual-Layer Architecture:**
251
+
252
+ | Layer | Field | Purpose | Use Cases |
253
+ |-------|-------|---------|-----------|
254
+ | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
255
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
256
+
257
+ **Primary Object Array Structure:**
258
+ ```javascript
259
+ primary: [
260
+ {
261
+ subject: string | null, // First non-fragment subject declaration
262
+ type: string | null, // First rdf:type declaration
263
+ label: string | null // First rdfs:label literal
264
+ },
265
+ // ... one object per document
266
+ ]
267
+ ```
268
+
264
269
 
265
270
  ### `generate({ quads, context, primarySubject })`
266
271
 
package/dist/README.md CHANGED
@@ -57,45 +57,12 @@ 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** - Instant access to primarySubject, primaryType, and primaryLabel for document identity
60
+ - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
61
61
 
62
62
  ## 🌟 What is MD-LD?
63
63
 
64
64
  MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
65
65
 
66
- ## ⚡ Performance & Architecture
67
-
68
- MD-LD v0.10.0 features a **character-based tokenization system** for optimal performance:
69
-
70
- - **20-28% faster parsing** than regex-based approaches
71
- - **Memory-efficient** with ~640 bytes per quad retained
72
- - **Streaming-friendly** with O(n) linear time complexity
73
- - **Character-based detection** replaces complex regex patterns
74
- - **Unified tokenizer architecture** in `src/tokenizers.js`
75
-
76
- ### Tokenizer Architecture
77
-
78
- The parser uses specialized character-based tokenizers:
79
-
80
- ```javascript
81
- // Block-level tokenizers
82
- detectFence() // ```code blocks
83
- detectPrefix() // [prefix] <iri>
84
- detectHeading() // # Headings
85
- detectList() // - List items
86
- detectBlockquote() // > Blockquotes
87
- detectStandaloneSubject() // {=subject}
88
-
89
- // Inline carrier scanner
90
- scanInlineCarriers() // [text], **bold**, `code`, <URL>
91
- ```
92
-
93
- This design provides:
94
- - **Better maintainability** - Easier to debug and extend
95
- - **Improved error handling** - More precise edge case detection
96
- - **Cleaner code structure** - No complex regex patterns
97
- - **Full backward compatibility** - All 127 tests passing
98
-
99
66
  ```markdown
100
67
  [my] <tag:alice@example.com,2026:>
101
68
  # 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
@@ -118,13 +85,15 @@ pnpm install mdld-parse
118
85
  ```javascript
119
86
  import { parse } from 'mdld-parse';
120
87
 
121
- const markdown = `# Document {=ex:doc .Article}
122
- [Alice] {author}`;
88
+ const markdown = `[ex] <tag:alice@example.org,2026:>
123
89
 
124
- const result = parse({
125
- text: markdown,
126
- context: { ex: 'http://example.org/' }
127
- });
90
+ # Demo document {=ex:example/doc .prov:Entity label}
91
+
92
+ > A demo document for MD-LD {comment}
93
+ [Alice] {+ex:alice ?ex:author .prov:Person label}
94
+ `;
95
+
96
+ const result = parse({ text: markdown });
128
97
 
129
98
  console.log(result.quads);
130
99
  // RDF/JS quads ready for n3.js, rdflib, etc.
@@ -136,7 +105,7 @@ console.log(result.quads);
136
105
  <script type="module">
137
106
  import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
138
107
 
139
- const result = parse('# Hello {=ex:hello label}');
108
+ const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
140
109
  </script>
141
110
  ```
142
111
 
@@ -154,9 +123,9 @@ Each predicate form determines the graph edge:
154
123
 
155
124
  | Form | Edge | Example | Meaning |
156
125
  |-------|---------|------------------------------|------------------|
157
- | `p` | S → L | `[Alice] {name}` | literal property |
126
+ | `p` | S → L | `[Alice] {label}` | literal property |
158
127
  | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
159
- | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
128
+ | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
160
129
 
161
130
  ## 📍 Elevated Statements
162
131
 
@@ -233,18 +202,33 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
233
202
  - `dataFactory` (object, optional) — Custom RDF/JS DataFactory
234
203
  - `graph` (string, optional) — Named graph IRI
235
204
 
236
- **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primaryType, primaryLabel, md }`
205
+ **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
237
206
 
238
207
  - `quads` — Array of RDF/JS Quads (final resolved graph state)
239
208
  - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
240
209
  - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
241
210
  - `origin` — Lean origin tracking object with quadIndex for UI navigation
242
211
  - `context` — Final context used (includes prefixes)
243
- - `primarySubject` — String IRI or null (first non-fragment subject declaration)
244
- - `primaryType` — String IRI or null (first rdf:type declaration)
245
- - `primaryLabel` — String or null (first rdfs:label literal)
212
+ - `primarySubject` — String IRI or null (canonical append identity)
213
+ - `primary` — Object containing primary metadata (semantic surface descriptor)
246
214
  - `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
247
215
 
216
+ **Dual-Layer Architecture:**
217
+
218
+ | Layer | Field | Purpose | Use Cases |
219
+ |-------|-------|---------|-----------|
220
+ | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
221
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
222
+
223
+ **Primary Object Structure:**
224
+ ```javascript
225
+ primary: {
226
+ subject: string | null, // First non-fragment subject declaration
227
+ type: string | null, // First rdf:type declaration
228
+ label: string | null // First rdfs:label literal
229
+ }
230
+ ```
231
+
248
232
  ### `merge(docs, options)`
249
233
 
250
234
  Merge multiple MDLD documents with diff polarity resolution.
@@ -254,13 +238,34 @@ Merge multiple MDLD documents with diff polarity resolution.
254
238
  - `options` (object, optional):
255
239
  - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
256
240
 
257
- **Returns:** `{ quads, remove, origin, context, primarySubjects }`
241
+ **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
258
242
 
259
243
  - `quads` — Array of RDF/JS Quads (final resolved graph state)
260
244
  - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
261
- - `origin` — Merge origin tracking with document index and polarity
262
- - `context` — Final merged context
263
- - `primarySubjects` — Array of string IRIs (primary subjects from each document, in merge order)
245
+ - `origin` — Merge origin with document tracking
246
+ - `context` — Final context used (includes prefixes)
247
+ - `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
248
+ - `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
249
+
250
+ **Dual-Layer Architecture:**
251
+
252
+ | Layer | Field | Purpose | Use Cases |
253
+ |-------|-------|---------|-----------|
254
+ | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
255
+ | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
256
+
257
+ **Primary Object Array Structure:**
258
+ ```javascript
259
+ primary: [
260
+ {
261
+ subject: string | null, // First non-fragment subject declaration
262
+ type: string | null, // First rdf:type declaration
263
+ label: string | null // First rdfs:label literal
264
+ },
265
+ // ... one object per document
266
+ ]
267
+ ```
268
+
264
269
 
265
270
  ### `generate({ quads, context, primarySubject })`
266
271
 
package/dist/docs/API.md CHANGED
@@ -14,15 +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, primaryType, primaryLabel, 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)
24
- - `primaryType` — String IRI or null (first rdf:type declaration)
25
- - `primaryLabel` — String or null (first rdfs:label literal)
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
+ ```
26
41
 
27
42
  > Legacy: `parse(text, options)` supported for backward compatibility (deprecated)
28
43
 
@@ -125,7 +140,7 @@ Merge multiple MDLD documents with diff polarity resolution.
125
140
  - `options` (object, optional):
126
141
  - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
127
142
 
128
- **Returns:** `{ quads, remove, origin, context }`
143
+ **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
129
144
 
130
145
  - `quads` — Merged array of RDF/JS Quads
131
146
  - `remove` — Array of retractions from merge process
@@ -133,6 +148,27 @@ Merge multiple MDLD documents with diff polarity resolution.
133
148
  - `documents` — Array of document metadata
134
149
  - `quadIndex` — Combined quad index from all documents
135
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
+ ```
136
172
 
137
173
  #### Basic Merge Example
138
174
 
@@ -530,13 +530,23 @@ for (let i = 0; i < tokens.length; i++) {
530
530
  // Process retractions and ensure hard invariant
531
531
  const filteredRemove = processRetractions(state.quads, state.removeSet);
532
532
 
533
- return {
534
- quads: state.quads, // Final resolved graph state
535
- remove: filteredRemove, // External retractions only
536
- statements: state.statements, // Elevated statements
537
- origin: state.origin, // Complete provenance
538
- context: state.ctx // Final prefix context
539
- };
533
+ // Create structured primary object for semantic surface
534
+ const primary = {
535
+ subject: state.primarySubject,
536
+ type: state.primaryType,
537
+ label: state.primaryLabel,
538
+ comment: state.primaryComment
539
+ };
540
+
541
+ return {
542
+ quads: state.quads, // Final resolved graph state
543
+ remove: filteredRemove, // External retractions only
544
+ statements: state.statements, // Elevated statements
545
+ origin: state.origin, // Complete provenance
546
+ context: state.ctx, // Final prefix context
547
+ primarySubject: state.primarySubject, // Canonical append identity
548
+ primary // Semantic surface descriptor
549
+ };
540
550
  ```
541
551
 
542
552
  #### Retraction Processing
@@ -1,16 +1,26 @@
1
1
  # Primary Metadata Example
2
2
 
3
- This example demonstrates the Primary Metadata feature in MD-LD, which provides immediate access to the main entity, type, and label described by a document.
3
+ This example demonstrates the Primary Metadata feature in MD-LD, which provides immediate access to the main entity, type, label, comment described by a document.
4
4
 
5
- ## Primary Metadata Trio
5
+ ## Primary Metadata Quartet
6
6
 
7
7
  MD-LD tracks three primary metadata fields during parsing to provide immediate document identity:
8
8
 
9
9
  | Field | Source | Purpose |
10
10
  |-------|--------|---------|
11
- | **primarySubject** | First non-fragment `{=subject}` | Document identity |
12
- | **primaryType** | First `.Class` declaration | Document category |
13
- | **primaryLabel** | First `{label}` literal | Human-readable name |
11
+ | **primarySubject** | First non-fragment `{=subject}` | Document identity (canonical append identity) |
12
+ | **primaryType** | First `rdf:type` declaration | Document category (semantic classification) |
13
+ | **primaryLabel** | First `rdfs:label` literal | Human-readable name (UI & display) |
14
+ | **primaryComment** | First `rdfs:comment` literal | Human-readable comment (UI & description) |
15
+
16
+ ## Dual-Layer Architecture
17
+
18
+ MD-LD implements a **dual-layer architecture** that separates concerns cleanly:
19
+
20
+ | Layer | Field | Role | Use Cases |
21
+ | ------ | ------ | --------- | ---------- |
22
+ | **Canonical Identity** | `primarySubject` | Storage, routing, synchronization, append operations |
23
+ | **Semantic Surface** | `primary` object | UI rendering, indexing, navigation, agent orientation |
14
24
 
15
25
  ## What is a Primary Subject?
16
26
 
@@ -20,10 +30,28 @@ The Primary Subject is the first non-fragment subject declaration (`{=IRI}`) in
20
30
 
21
31
  The Primary Type is the first `rdf:type` declaration associated with the Primary Subject. It provides a way to identify the type of the main entity described by a document.
22
32
 
33
+ ### 1. First Type Declaration Wins
34
+
35
+ ```markdown
36
+ # Person {=my:alice .prov:Person .schema:Person}
37
+ [Details] {label}
38
+ ```
39
+
40
+ `primaryType` captures the **first rdf:type assertion emitted while current subject == primarySubject**. This is parser-precise and avoids ambiguity with later type declarations for other entities.
41
+
23
42
  ## What is a Primary Label?
24
43
 
25
44
  The Primary Label is the first `rdfs:label` literal associated with the Primary Subject. It provides a human-readable name for the main entity described by a document.
26
45
 
46
+ ### 2. First Label Declaration Wins
47
+
48
+ ```markdown
49
+ # Person {=my:alice .prov:Person label}
50
+ [Alice Smith] {rdfs:label}
51
+ ```
52
+
53
+ `primaryLabel` captures the **first emitted rdfs:label literal while current subject == primarySubject**. This ensures the label is associated with the primary subject, not other entities in the document.
54
+
27
55
  ## Example Document
28
56
 
29
57
  ```markdown
@@ -53,13 +81,17 @@ const md = `[ex] <tag:alice@example.org,2026:articles/>
53
81
 
54
82
  const result = parse({ text: md });
55
83
 
84
+ // Canonical append identity
56
85
  console.log('Primary Subject:', result.primarySubject);
57
- console.log('Primary Type:', result.primaryType);
58
- console.log('Primary Label:', result.primaryLabel);
86
+ // Semantic surface descriptor
87
+ console.log('Primary Object:', result.primary);
59
88
  // Output:
60
89
  // Primary Subject: tag:alice@example.org,2026:articles/understanding-primary-subject
61
- // Primary Type: http://schema.org/Article
62
- // Primary Label: Understanding Primary Subjects
90
+ // Primary Object: {
91
+ // subject: 'tag:alice@example.org,2026:articles/understanding-primary-subject',
92
+ // type: 'http://schema.org/Article',
93
+ // label: 'Understanding Primary Subjects'
94
+ // }
63
95
  ```
64
96
 
65
97
  ## Key Behaviors
@@ -115,8 +147,16 @@ const doc2 = `[ex] <http://example.org/>
115
147
 
116
148
  const result = merge([doc1, doc2], { context: { ex: 'http://example.org/' } });
117
149
 
118
- console.log(result.primarySubjects.map(s => s.value));
119
- // Output: ['http://example.org/doc1', 'http://example.org/doc2']
150
+ // Canonical append identities
151
+ console.log('Primary Subjects:', result.primarySubjects);
152
+ // Semantic surface descriptors
153
+ console.log('Primary Objects:', result.primary);
154
+ // Output:
155
+ // Primary Subjects: ['http://example.org/doc1', 'http://example.org/doc2']
156
+ // Primary Objects: [
157
+ // { subject: 'http://example.org/doc1', type: 'http://schema.org/Article', label: 'Document 1' },
158
+ // { subject: 'http://example.org/doc2', type: 'http://schema.org/Article', label: 'Document 2' }
159
+ // ]
120
160
  ```
121
161
 
122
162
  ## Use Cases
@@ -206,13 +246,18 @@ const doc1 = `[blog] <https://example.com/blog/>
206
246
  [Hello World] {schema:headline}`;
207
247
 
208
248
  const result1 = parse({ text: doc1, context: { blog: 'https://example.com/blog/', schema: 'http://schema.org/' } });
249
+
250
+ // Canonical append identity
209
251
  console.log('Primary Subject:', result1.primarySubject);
210
- console.log('Primary Type:', result1.primaryType);
211
- console.log('Primary Label:', result1.primaryLabel);
252
+ // Semantic surface descriptor
253
+ console.log('Primary Object:', result1.primary);
212
254
  // Output:
213
255
  // Primary Subject: https://example.com/blog/post1
214
- // Primary Type: http://schema.org/BlogPosting
215
- // Primary Label: My First Post
256
+ // Primary Object: {
257
+ // subject: 'https://example.com/blog/post1',
258
+ // type: 'http://schema.org/BlogPosting',
259
+ // label: 'My First Post'
260
+ // }
216
261
 
217
262
  // Multiple documents
218
263
  const doc2 = `[blog] <https://example.com/blog/>
@@ -221,8 +266,16 @@ const doc2 = `[blog] <https://example.com/blog/>
221
266
 
222
267
  const merged = merge([doc1, doc2], { context: { blog: 'https://example.com/blog/', schema: 'http://schema.org/' } });
223
268
 
224
- console.log('Primary subjects:', merged.primarySubjects);
225
- // Output: ['https://example.com/blog/post1', 'https://example.com/blog/post2']
269
+ // Canonical append identities
270
+ console.log('Primary Subjects:', merged.primarySubjects);
271
+ // Semantic surface descriptors
272
+ console.log('Primary Objects:', merged.primary);
273
+ // Output:
274
+ // Primary Subjects: ['https://example.com/blog/post1', 'https://example.com/blog/post2']
275
+ // Primary Objects: [
276
+ // { subject: 'https://example.com/blog/post1', type: 'http://schema.org/BlogPosting', label: 'My First Post' },
277
+ // { subject: 'https://example.com/blog/post2', type: 'http://schema.org/BlogPosting', label: 'My Second Post' }
278
+ // ]
226
279
  ```
227
280
 
228
281
  ## Document Identity Trio
@@ -232,19 +285,42 @@ The primary metadata trio provides sufficient document/append stream identity fo
232
285
  ```javascript
233
286
  // Nostr integration example
234
287
  const nostrTags = [
235
- ['s', result.primarySubject], // subject addressing
236
- ['t', result.primaryType], // type filtering
237
- ['d', result.primaryLabel] // display identifier
288
+ ['s', result.primarySubject], // subject addressing (canonical)
289
+ ['t', result.primary.type], // type filtering
290
+ ['d', result.primary.label] // display identifier
238
291
  ];
239
292
 
240
293
  // Document fingerprint
241
294
  const fingerprint = {
242
- subject: result.primarySubject, // What the document is about
243
- type: result.primaryType, // What kind of document
244
- label: result.primaryLabel // Human-readable name
295
+ canonical: result.primarySubject, // What the document is about (append identity)
296
+ semantic: result.primary // How to present and index the document
245
297
  };
246
298
  ```
247
299
 
300
+ ## Primary Metadata is Parser-Level Metadata
301
+
302
+ **Important**: Primary metadata is derived parser state and does not introduce additional RDF triples or semantic entailments. It describes document intent, not graph semantics.
303
+
304
+ ### Key Distinctions
305
+
306
+ | Aspect | Primary Metadata | RDF Semantics |
307
+ |---------|------------------|----------------|
308
+ | **Source** | Parser extraction rules | Triple patterns |
309
+ | **Scope** | Document-level intent | Graph-level relationships |
310
+ | **Purpose** | Routing, UI, indexing | Reasoning, inference |
311
+ | **Stability** | Deterministic extraction | Dynamic inference |
312
+
313
+ ### Stability Guarantees
314
+
315
+ `primarySubject` is **stable under rewrite() operations that preserve extracted quads**. This means:
316
+
317
+ - Append routing remains consistent across document updates
318
+ - Synchronization identity is preserved during merges
319
+ - File mapping stays stable through rewrite operations
320
+ - Index references remain valid
321
+
322
+ This stability is crucial for distributed systems and local-first architectures.
323
+
248
324
  ## Specification
249
325
 
250
326
  For complete details on Primary Subject semantics, see the [MD-LD Specification](../spec/Spec.md#17-primary-subject).