Feature/oldm turtle

MUZE_ALIGNMENT.md

@@ -53,7 +53,7 @@ OLDM is aligned with Muze’s sovereign-web goals because it tries to make Linke
 
 **Status:** Partly addressed
 
-**Note:** The package is now split so `@muze-nl/oldm-core` has no direct N3 dependency and the N3 integration lives in `@muze-nl/oldm-n3`. The beginner package still uses N3 by default, so a fully import-map-compatible Turtle adapter remains a future improvement.
+**Note:** The package is now split so `@muze-nl/oldm-core` has no direct N3 dependency and the N3 integration lives in `@muze-nl/oldm-n3`. The beginner package now publishes both ESM bundles and a classic global IIFE bundle, so plain script-tag usage is supported again. The beginner package still uses N3 by default, so a fully import-map-compatible Turtle adapter remains a future improvement.
 
 ### 2. Document semantic tradeoffs of object mapping
 
@@ -65,7 +65,9 @@ OLDM is aligned with Muze’s sovereign-web goals because it tries to make Linke
 
 **Suggested direction:** Add a “What is preserved / what is simplified” section. Include examples of cycles, one-or-many values, literals with types/languages, and subject identity.
 
-**Status:** Open
+**Status:** Partly addressed
+
+**Note:** `Context` now keeps a registry of parsed graphs, exposes a combined read view, provides `context.sources(subject, predicate, value)` for provenance inspection, supports source-aware write helpers through `graph.set/add/delete()` and `context.set/add/delete(..., { graph })`, and routes direct property assignment on named subjects from `context.get(...)` through the same conservative graph resolver. Blank nodes remain graph-scoped and collection mutation is still intentionally conservative.
 
 ### 3. Separate core graph/object mapping from parser/writer adapters
 
@@ -108,3 +110,8 @@ OLDM is aligned with Muze’s sovereign-web goals because it tries to make Linke
 ## Review cadence
 
 Review this document before feature work, before releases, and whenever the public API or dependency surface changes. Close issues by changing their status to `Done` and leaving a short note about the decision.
+
+
+## Experimental Turtle adapter
+
+The repository now contains `@muze-labs/oldm-turtle`, an experimental non-streaming Turtle 1.1 parser/writer adapter. It is a better long-term fit for Muze principles than the broad N3 dependency, but it is not the default yet. The current investigation shows a substantial browser bundle reduction if it replaces N3, while small Solid-style parse/write performance is roughly comparable. See `docs/TURTLE_PARSER_INVESTIGATION.md`.

README.md

@@ -40,12 +40,74 @@ const context = oldm({
 })
 ```
 
-## Browser bundle
 
-The friendly package builds browser bundles into `packages/oldm/dist/`:
+## Multiple graphs in one context
+
+A context keeps a registry of every parsed graph. Each `context.parse()` call still returns a `Graph` for the parsed resource, while the context exposes a combined view over all graphs loaded into that context.
+
+```javascript
+const context = oldm.context()
+
+const profile = context.parse(profileTurtle, profileUrl, 'text/turtle')
+const settings = context.parse(settingsTurtle, settingsUrl, 'text/turtle')
+
+profile.get(`${profileUrl}#me`)       // data from only the profile graph
+context.get(`${profileUrl}#me`)       // merged data from all graphs
+context.graphs                        // [profile, settings]
+context.graph(profileUrl)             // profile
+context.data                          // combined subject list
+context.subjects                      // combined subject map by full URI
+context.sources(context.get(`${profileUrl}#me`))
+// [profile, settings] when both graphs contain data for that subject
+context.sources(context.get(`${profileUrl}#me`), 'vcard$fn')
+// [profile] when only the profile graph contains that property
+```
+
+The combined view merges named subjects by IRI and keeps the original graph views separate. `context.sources(subject, predicate, value)` can be used to inspect which graph contributed a subject, property, or specific property value.
+
+For source-aware writes, use the graph-specific helpers when you know the resource you want to edit:
+
+```javascript
+profile.set(`${profileUrl}#me`, 'vcard$fn', 'Auke')
+profile.add(`${profileUrl}#me`, 'schema$knowsAbout', 'Linked Data')
+profile.delete(`${profileUrl}#me`, 'schema$knowsAbout', 'Old value')
+```
+
+Or use context-level helpers with an explicit graph:
+
+```javascript
+context.set(`${profileUrl}#me`, 'vcard$fn', 'Auke', { graph: profile })
+context.add(`${profileUrl}#me`, 'schema$knowsAbout', 'Solid', { graph: profileUrl })
+```
+
+When no graph is passed, `context.set/add/delete()` uses a conservative default: the subject's exact graph URL, the subject document URL without a fragment, the only graph that currently contains the subject, the configured `defaultGraph`, or the only graph in the context. Direct property assignment on a named subject from `context.get(...)` uses the same resolver, so simple edits can stay object-like:
+
+```javascript
+const me = context.get(`${profileUrl}#me`)
+me.vcard$fn = 'Auke'
+delete me.vcard$nickname
+```
+
+If there is no obvious source graph, OLDM throws and asks you to choose one explicitly with `context.set/add/delete(..., { graph })` or `graph.set/add/delete(...)`.
+
+## Browser bundles
+
+The friendly package builds browser bundles into `packages/oldm/dist/`: an ESM bundle for module scripts and a classic global IIFE bundle for plain script tags.
+
+For modern module scripts:
+
+```html
+<script type="module">
+  import oldm from 'https://cdn.jsdelivr.net/npm/@muze-nl/oldm/dist/oldm.min.js'
+
+  const context = oldm.context()
+</script>
+```
+
+For a classic script tag that creates `globalThis.oldm`:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@muze-nl/oldm/dist/oldm.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@muze-nl/oldm/dist/oldm.global.min.js"></script>
 <script>
   const context = oldm.context()
 </script>
@@ -102,3 +164,8 @@ console.log(source.primary.vcard$fn)
 ## License
 
 MIT. See [LICENSE](./LICENSE).
+
+
+## Turtle parser investigation
+
+An experimental small Turtle 1.1 parser/writer adapter lives in `packages/oldm-turtle` as `@muze-labs/oldm-turtle`. It is not the default yet; see `docs/TURTLE_PARSER_INVESTIGATION.md` for supported syntax, size comparison, and small Solid-style benchmark results.