logseq-matryca-parser 1.8.2__tar.gz → 1.9.0__tar.gz

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/.github/workflows/ci.yml

@@ -111,7 +111,11 @@ jobs:
           --output-file "${{ runner.temp }}/requirements-audit.txt"
 
       - name: Audit exported dependencies
-        run: uv run pip-audit --no-deps --disable-pip -r "${{ runner.temp }}/requirements-audit.txt"
+        # Temporary exception governed by docs/security/DEPENDENCY_ADVISORY_EXCEPTIONS.md.
+        run: >-
+          uv run pip-audit --no-deps --disable-pip
+          --ignore-vuln PYSEC-2026-3740
+          -r "${{ runner.temp }}/requirements-audit.txt"
 
   package-contract:
     name: Wheel and source distribution contract

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/.github/workflows/pypi_publish.yml

@@ -40,7 +40,10 @@ jobs:
       - name: Audit production dependencies
         run: |
           uv export --all-extras --no-dev --no-emit-workspace -o "${{ runner.temp }}/requirements-audit.txt"
-          uv run pip-audit --no-deps --disable-pip -r "${{ runner.temp }}/requirements-audit.txt"
+          # Temporary exception governed by docs/security/DEPENDENCY_ADVISORY_EXCEPTIONS.md.
+          uv run pip-audit --no-deps --disable-pip \
+            --ignore-vuln PYSEC-2026-3740 \
+            -r "${{ runner.temp }}/requirements-audit.txt"
 
       - name: Run full quality gate
         run: make all

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/AGENTS.md

@@ -20,7 +20,7 @@ backlinks, exports, visualizations, and AI chunks are derived views.
 | **SYNAPSE** | Export lineage-aware LangChain documents, LlamaIndex nodes, and enriched chunks | `SynapseAdapter` |
 | **FORGE** | Serialize JSON, clean Markdown, Logseq pages, and Obsidian-compatible output | `ForgeExporter`, `serialize_logseq_page` |
 | **KINETIC** | Run CLI parse, export, scan, visualize, agent-read, and agent-write workflows | `matryca-parse` |
-| **LENS** | Build an interactive graph visualization | `GraphVisualizer` |
+| **LENS** | Build a compatible reference-topology visualization; planned compatible deprecation follows a later Trama UI migration | `GraphVisualizer` |
 | **Agent access** | Read a token-efficient X-Ray outline or perform bounded writes | `agent-read`, `agent-write`, `logseq_agent_write` |
 
 ## Start here

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.9.0] - 2026-09-06
+
+### Added
+
+- **In-memory snapshot graph factory** — `SnapshotPage` and
+  `LogseqGraph.from_snapshot_pages()` build the existing parser graph indexes from
+  bounded, caller-captured Markdown without source discovery, file reopening, or
+  graph-root filesystem inspection.
+  The stable additive API preserves deterministic ordering, parser identities,
+  aliases, backlinks, diagnostics, and opt-in strict modes while keeping source
+  capture and cross-product projection outside Parser (#209).
+
+### Security
+
+- **Time-bounded NLTK advisory exception** — document the exact optional AI
+  dependency exposure, non-reachability evidence, compensating controls,
+  owner, upstream advisory, and 2026-10-05 expiry for `PYSEC-2026-3740` while
+  no patched NLTK registry release exists. CI and release audits ignore only
+  that advisory; all other dependency findings remain fail-closed.
+
+### Changed
+
+- **LENS Stage 0 transition** — mark the compatible `GraphVisualizer`,
+  `visualize`, and `demo` surfaces as transitional and feature-frozen, with
+  Matryca Trama as future user-facing graph-intelligence destination. This
+  release makes no API removal or deprecation-warning change (#213).
+- **Parser-Plumber boundary** — record Parser as the deterministic Logseq OG
+  parsing library and Plumber as the sole cross-product Logseq gateway to
+  Trama and Brain. Existing Parser APIs and LENS behavior remain compatible;
+  any Trama UI migration requires a later, separately reviewed compatible
+  deprecation plan (#203).
+
 ## [1.8.2] - 2026-08-30
 
 ### Changed

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/CONTRIBUTING.md

@@ -17,7 +17,7 @@ User-facing behavior is documented in:
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — LOGOS, SYNAPSE, `LogseqGraph`, agents, and data flow
 - [`docs/internal/LOCAL_CODE_STUDY.md`](docs/internal/LOCAL_CODE_STUDY.md) — maintainer local code audit runbook (not for public issues/CHANGELOG)
 - [`docs/logseq_ast_primer.md`](docs/logseq_ast_primer.md) — Logseq Spatial Markdown domain rules
-- [`CHANGELOG.md`](CHANGELOG.md) — release candidate **1.8.2**, latest published release **1.8.1**, and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — latest release **1.9.0** and **Unreleased** changes (Keep a Changelog)
 - [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) — version bump, tag, and PyPI publish checklist
 - [`docs/CI_ASSURANCE.md`](docs/CI_ASSURANCE.md) — pull-request, scheduled, settings-managed, and release checks
 - [`docs/CODEQL.md`](docs/CODEQL.md) — CodeQL default setup (no custom `codeql.yml`)

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.8.2
+Version: 1.9.0
 Summary: The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai.
 Project-URL: Homepage, https://github.com/MarcoPorcellato/logseq-matryca-parser
 Project-URL: Repository, https://github.com/MarcoPorcellato/logseq-matryca-parser
@@ -89,7 +89,8 @@ selected by the caller.
 - **Parse and query:** load one page or a complete vault as a typed AST and graph.
 - **Build RAG context:** export LangChain documents, LlamaIndex nodes, or enriched chunks.
 - **Move knowledge:** generate JSON, clean Markdown, or an Obsidian vault.
-- **Visualize:** render an interactive graph with LENS.
+- **Visualize:** render an interactive reference-topology graph with the transitional,
+  feature-frozen LENS adapter.
 - **Use an AI agent:** start from [`AGENTS.md`](AGENTS.md) or the concise [`llms.txt`](llms.txt) index.
 
 ---
@@ -188,6 +189,13 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 The base parser is local-first and has zero telemetry. Optional AI, watcher, and
 visualization dependencies remain lazy. See the [architecture](docs/ARCHITECTURE.md)
 and [API stability reference](docs/reference/API_STABILITY.md) for exact boundaries.
+For cross-product Logseq OG use, Plumber is the gateway to Trama and Brain;
+Parser remains the deterministic parsing stage. LENS stays compatible while a
+future Trama graph-intelligence migration is separately designed and released.
+Stage 0 marks LENS as transitional and feature-frozen: `GraphVisualizer`,
+`matryca-parse visualize`, and `matryca-parse demo` remain available without a
+deprecation warning. Matryca Trama is the destination for future user-facing
+graph intelligence.
 
 ### Data model — `LogseqNode` task fields
 
@@ -219,7 +227,7 @@ uv sync --all-extras
 ```
 
 ```bash
-# 1. Visualize your local graph (LENS)
+# 1. Visualize your local graph (LENS: transitional, feature-frozen)
 matryca-parse visualize /path/to/logseq/graph my-map.html
 
 # 2. Export for AI / RAG (SYNAPSE)
@@ -258,6 +266,14 @@ graph = LogseqGraph.load_directory("/path/to/logseq/graph")
 page_obj = graph.get_page("My Page")  # case-insensitive
 effective = graph.get_effective_properties(page_obj.root_nodes[0].uuid)
 
+# Build the same in-memory indexes from caller-captured Markdown without filesystem access.
+from logseq_matryca_parser import SnapshotPage
+
+snapshot_graph = LogseqGraph.from_snapshot_pages(
+    "/path/to/logseq/graph",
+    [SnapshotPage("pages/Project.md", "- Captured block\n")],
+)
+
 # Export to LangChain with lineage metadata
 docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
 
@@ -288,7 +304,9 @@ assert result["status"] == "success"
 ---
 
 ## 🗺️ Roadmap
-- [ ] **Desktop GUI:** Standalone app for non-technical users. [(Join the RFC)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)
+- [ ] **Graph-intelligence UI:** A future Matryca Trama surface may succeed the
+  compatible Parser LENS workflow after a separately reviewed migration; Parser
+  does not commit to a standalone GUI. [(Track the historical RFC)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)
 - [x] **Obsidian Adapter:** Native CLI export (`--format obsidian`) with YAML frontmatter and `^` block anchors.
 - [ ] **Ollama Integration:** One-click local RAG setup. [(RFC draft)](docs/rfc/OLLAMA_RAG.md) · [(Track progress #34)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)
 
@@ -323,7 +341,8 @@ Read the complete [release highlights](RELEASE_HIGHLIGHTS.md), the exhaustive
 [changelog](CHANGELOG.md), or the signed artifacts on
 [GitHub Releases](https://github.com/MarcoPorcellato/logseq-matryca-parser/releases).
 
-- **v1.8.2 (release candidate)** — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and `Path | str` graph loading.
+- **v1.9.0** — Adds the stable in-memory snapshot graph factory, clarifies the Parser-Plumber boundary, and governs the temporary optional-NLTK advisory exception.
+- **v1.8.2** — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and `Path | str` graph loading.
 - **v1.8.1** — Hardened deep-outline parsing, coherent incremental graph mutations, bounded assurance cleanup, and stable provenance for optional NLTK.
 - **v1.8.0** — Added bounded privacy-safe local graph assurance, source-location contracts, and the first internal parser line-classification phase.
 - **v1.7.1** — Added the runnable offline SYNAPSE RAG example and tightened release-note and optional-dependency security checks.

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/README.md

@@ -48,7 +48,8 @@ selected by the caller.
 - **Parse and query:** load one page or a complete vault as a typed AST and graph.
 - **Build RAG context:** export LangChain documents, LlamaIndex nodes, or enriched chunks.
 - **Move knowledge:** generate JSON, clean Markdown, or an Obsidian vault.
-- **Visualize:** render an interactive graph with LENS.
+- **Visualize:** render an interactive reference-topology graph with the transitional,
+  feature-frozen LENS adapter.
 - **Use an AI agent:** start from [`AGENTS.md`](AGENTS.md) or the concise [`llms.txt`](llms.txt) index.
 
 ---
@@ -147,6 +148,13 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 The base parser is local-first and has zero telemetry. Optional AI, watcher, and
 visualization dependencies remain lazy. See the [architecture](docs/ARCHITECTURE.md)
 and [API stability reference](docs/reference/API_STABILITY.md) for exact boundaries.
+For cross-product Logseq OG use, Plumber is the gateway to Trama and Brain;
+Parser remains the deterministic parsing stage. LENS stays compatible while a
+future Trama graph-intelligence migration is separately designed and released.
+Stage 0 marks LENS as transitional and feature-frozen: `GraphVisualizer`,
+`matryca-parse visualize`, and `matryca-parse demo` remain available without a
+deprecation warning. Matryca Trama is the destination for future user-facing
+graph intelligence.
 
 ### Data model — `LogseqNode` task fields
 
@@ -178,7 +186,7 @@ uv sync --all-extras
 ```
 
 ```bash
-# 1. Visualize your local graph (LENS)
+# 1. Visualize your local graph (LENS: transitional, feature-frozen)
 matryca-parse visualize /path/to/logseq/graph my-map.html
 
 # 2. Export for AI / RAG (SYNAPSE)
@@ -217,6 +225,14 @@ graph = LogseqGraph.load_directory("/path/to/logseq/graph")
 page_obj = graph.get_page("My Page")  # case-insensitive
 effective = graph.get_effective_properties(page_obj.root_nodes[0].uuid)
 
+# Build the same in-memory indexes from caller-captured Markdown without filesystem access.
+from logseq_matryca_parser import SnapshotPage
+
+snapshot_graph = LogseqGraph.from_snapshot_pages(
+    "/path/to/logseq/graph",
+    [SnapshotPage("pages/Project.md", "- Captured block\n")],
+)
+
 # Export to LangChain with lineage metadata
 docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
 
@@ -247,7 +263,9 @@ assert result["status"] == "success"
 ---
 
 ## 🗺️ Roadmap
-- [ ] **Desktop GUI:** Standalone app for non-technical users. [(Join the RFC)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)
+- [ ] **Graph-intelligence UI:** A future Matryca Trama surface may succeed the
+  compatible Parser LENS workflow after a separately reviewed migration; Parser
+  does not commit to a standalone GUI. [(Track the historical RFC)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)
 - [x] **Obsidian Adapter:** Native CLI export (`--format obsidian`) with YAML frontmatter and `^` block anchors.
 - [ ] **Ollama Integration:** One-click local RAG setup. [(RFC draft)](docs/rfc/OLLAMA_RAG.md) · [(Track progress #34)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)
 
@@ -282,7 +300,8 @@ Read the complete [release highlights](RELEASE_HIGHLIGHTS.md), the exhaustive
 [changelog](CHANGELOG.md), or the signed artifacts on
 [GitHub Releases](https://github.com/MarcoPorcellato/logseq-matryca-parser/releases).
 
-- **v1.8.2 (release candidate)** — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and `Path | str` graph loading.
+- **v1.9.0** — Adds the stable in-memory snapshot graph factory, clarifies the Parser-Plumber boundary, and governs the temporary optional-NLTK advisory exception.
+- **v1.8.2** — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and `Path | str` graph loading.
 - **v1.8.1** — Hardened deep-outline parsing, coherent incremental graph mutations, bounded assurance cleanup, and stable provenance for optional NLTK.
 - **v1.8.0** — Added bounded privacy-safe local graph assurance, source-location contracts, and the first internal parser line-classification phase.
 - **v1.7.1** — Added the runnable offline SYNAPSE RAG example and tightened release-note and optional-dependency security checks.

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/RELEASE_HIGHLIGHTS.md

@@ -5,13 +5,25 @@ For the exhaustive change history, see the [changelog](CHANGELOG.md). For
 published artifacts and attestations, see
 [GitHub Releases](https://github.com/MarcoPorcellato/logseq-matryca-parser/releases).
 
-## v1.8.2 (release candidate)
+## Unreleased
 
-Release candidate — strengthens the hosted assurance boundary, clarifies
+## v1.9.0
+
+Minor release — adds a stable in-memory graph factory and clarifies the
+cross-product integration boundary. **No intentional breaking changes** to
+stable package imports or CLI behavior.
+
+| Area | Change |
+| :--- | :--- |
+| **Graph API** | `SnapshotPage` and `LogseqGraph.from_snapshot_pages()` build ordinary in-memory graph indexes from bounded caller-captured Markdown. The additive API never discovers, reopens, or inspects logical source paths or its graph-root label; source capture, revisions, and external DTO projection remain outside Parser. |
+| **Architecture** | Parser remains the deterministic Logseq OG library. Plumber is the sole cross-product gateway to Trama and Brain; existing Parser APIs and LENS behavior remain compatible. |
+| **Dependency security** | A time-bounded, evidence-backed exception governs `PYSEC-2026-3740` for optional AI dependency NLTK until a patched registry release exists; all other dependency findings remain fail-closed. |
+
+## v1.8.2
+
+Patch release — strengthens the hosted assurance boundary, clarifies
 integration guidance, and makes the graph loader easier to call. **No
-intentional breaking changes** to stable package imports or CLI behavior. The
-v1.8.2 tag, PyPI publication, GitHub Release, hashes, and attestations remain
-pending the release workflow.
+intentional breaking changes** to stable package imports or CLI behavior.
 
 | Area | Change |
 | :--- | :--- |

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/SECURITY.md

@@ -2,13 +2,12 @@
 
 ## Supported Versions
 
-Security fixes are provided **only for the latest released version** on [PyPI](https://pypi.org/project/logseq-matryca-parser/). Until the v1.8.2 tag workflow completes, that version remains v1.8.1.
+Security fixes are provided **only for the latest released version** on [PyPI](https://pypi.org/project/logseq-matryca-parser/). The latest supported release is v1.9.0.
 
 | Version | Supported |
 | ------- | --------- |
-| 1.8.2 (release candidate; not published) | Pending publication |
-| **1.8.1** (latest released) | Yes |
-| 1.8.0 and older | No |
+| **1.9.0** (latest released) | Yes |
+| 1.8.2 and older | No |
 
 We recommend always running the current release and upgrading promptly when a security advisory is published.
 

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/ARCHITECTURE.md

@@ -28,6 +28,22 @@ Full contributor contract: [`CLEAN_CODE_ARCHITECTURE.md`](CLEAN_CODE_ARCHITECTUR
 
 High-level data flow from sovereign graph files through deterministic parsing to AST-backed exporters and adapters.
 
+## Cross-repository boundary
+
+For Logseq OG integration, Parser is the deterministic parsing stage in this
+data flow:
+
+```text
+Logseq OG -> Parser -> Plumber -> Trama/Brain
+```
+
+Parser owns the typed AST, in-memory graph, and parser-native serialization.
+Plumber owns source selection, host adapters, sessions, and public cross-product
+contracts. The flow does not add Python imports: Parser runtime does not import
+Plumber, Trama, or Brain, while Trama and Brain consume Plumber contracts and
+do not import or know Parser. Details and compatibility consequences are in
+[ADR-0004](decisions/ADR-0004-PARSER-PLUMBER-BOUNDARY.md).
+
 ```mermaid
 flowchart LR
     FS[(Local Logseq\nGraph .md)] --> Logos[LOGOS Engine\nParser]
@@ -308,6 +324,8 @@ When LENS receives a loaded **`LogseqGraph`**, wikilinks resolve through `get_pa
 
 Visualization export uses **`pyvis`** with **`force_atlas_2based`** physics, fullscreen canvas, HUD filters, glassmorphism control chrome, and stabilized layout configuration suitable for **large graphs at interactive frame rates** in the browser (product positioning targets fluid exploration of graphs on the order of **10⁴ nodes**).
 
+LENS remains fully compatible as a Parser reference-topology tool. Trama owns future product-intelligence visualization. Any later migration must preserve compatibility through a separately reviewed deprecation plan. No migration, warning, removal, or changed command is part of this repository slice.
+
 ### 3.4 AGENT WRITER — Append-Only Sandboxing & Headless Splicer
 
 In the **LLM OS** metaphor, **LOGOS** is the **read path** into the hierarchical “disk”: it materializes Spatial Markdown into a **deterministic AST** that downstream adapters trust. **`agent_writer`** ([`logseq_matryca_parser.agent_writer`](../src/logseq_matryca_parser/agent_writer.py)) is the complementary **bounded write syscall** with two surfaces:

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/CLEAN_CODE_ARCHITECTURE.md

@@ -8,8 +8,8 @@ audience: contributors
 owner: logseq-matryca-parser
 authority: source_repository
 execution_mode: reviewed
-last_verified: 2026-08-30
-verified: 2026-08-30
+last_verified: 2026-09-05
+verified: 2026-09-05
 stale_after: 2027-02-26
 okf_profile: matryca_okf_inspired_quality
 okf_spec_version: null
@@ -19,7 +19,7 @@ superseded_by: null
 
 # Clean Code & Clean Architecture — Logseq Matryca Parser
 
-**Version:** documents **v1.8.2** maintainer contracts (v1 structural backlog complete; parser, graph-coherence, and local-assurance slices merged)
+**Version:** documents **v1.9.0** maintainer contracts (v1 structural backlog complete; parser, graph-coherence, local-assurance, and stable snapshot-graph slices merged)
 **Audience:** contributors and Cursor agents patching `src/logseq_matryca_parser/`  
 **Companion:** [`ARCHITECTURE.md`](ARCHITECTURE.md) (LOGOS domain contract) · [`BUG_HUNT_REPORT.md`](BUG_HUNT_REPORT.md) (audit evidence) · [`CONTRIBUTING.md`](../CONTRIBUTING.md)
 
@@ -27,7 +27,14 @@ This document applies **Robert C. Martin's** *Clean Architecture* (dependency ru
 
 **Adoption model:** **incremental v1**. A full hexagonal package split (`domain/ports.py`, separate driver packages) is **out of scope** for routine PRs. Uncle Bob here is a **quality contract**, not a mandate to rewrite the flat `src/logseq_matryca_parser/` layout in one change.
 
-**Downstream consumer:** [Matryca Plumber](https://github.com/MarcoPorcellato/matryca-plumber) depends on this library as the inner AST ring. Public APIs (`LogseqGraph`, `StackMachineParser`, `SynapseAdapter`, agent write helpers) must stay stable and framework-agnostic.
+**Cross-repository boundary:** Parser owns deterministic OG parsing, typed ASTs,
+the in-memory graph, and parser-native serialization. [Matryca
+Plumber](https://github.com/MarcoPorcellato/matryca-plumber) may depend on it
+as an internal OG parser and is the sole cross-product Logseq gateway to Trama
+and Brain. Parser does not select sources, operate host adapters, or define
+public `plumber.*` contracts. Public APIs (`LogseqGraph`, `StackMachineParser`,
+`SynapseAdapter`, agent write helpers) stay stable and framework-agnostic; see
+[ADR-0004](decisions/ADR-0004-PARSER-PLUMBER-BOUNDARY.md).
 
 ---
 
@@ -54,6 +61,10 @@ This document applies **Robert C. Martin's** *Clean Architecture* (dependency ru
 | **Adapters** | `synapse.py`, `forge.py`, `agent_writer.py`, `agent_press.py`, `lens.py` | Framework projections (LangChain, LlamaIndex, Obsidian, PyVis) |
 | **Drivers** | `kinetic.py`, `kinetic_commands.py`, `kinetic_export.py`, `__main__.py` | Operator CLI — orchestrates use cases and adapters |
 
+Parser runtime modules must not import Plumber, Trama, or Brain. Trama and Brain
+consume Plumber contracts and do not import or know Parser. This is a product
+boundary, not a reason to move existing Parser APIs or LENS behavior in place.
+
 ```mermaid
 flowchart TB
   subgraph drivers [Drivers]
@@ -99,6 +110,7 @@ flowchart TB
 | Adapters must not import `kinetic` | same |
 | Import cycles between `src/` modules | `0` expected — verify via local graph study (`check` cycles) |
 | Adapters use **public** `LogseqGraph` APIs | Code review + audit SOP |
+| Parser runtime does not import Plumber, Trama, or Brain | [`tests/test_layer_boundary.py`](../tests/test_layer_boundary.py) |
 
 ### v1 by design (do not "fix" without an epic)
 
@@ -137,7 +149,7 @@ make check
 
 | Area | Responsibility |
 |------|----------------|
-| Bulk load | `load_directory`, `_enrich_pages_index` |
+| Bulk load | `load_directory`, `from_snapshot_pages`, `_enrich_pages_index` |
 | Incremental | `invalidate_and_reload_page`, watcher |
 | Coherence | Per-graph in-process coordinator shared by readers, writer splices, and watcher reloads |
 | Query | `GraphQuery`, `search_content`, backlinks |
@@ -159,6 +171,15 @@ pending timers, and waits for admitted routes to finish; callbacks stay FIFO,
 isolated, outside graph coordination, and use a separate bounded dispatcher
 close.
 
+`SnapshotPage` plus `LogseqGraph.from_snapshot_pages()` is the additive
+in-memory bulk-load boundary. It accepts caller-captured Markdown text and safe
+graph-relative logical paths, parses only through `StackMachineParser.parse()`, and
+then reuses the normal graph index builders. The factory neither discovers nor
+reopens or inspects source paths or the graph-root label; those synthetic paths are
+graph metadata only. Capture,
+filesystem authority, revisions, and cross-product DTO projection remain outside
+Parser.
+
 The private inventory and snapshot representations are implementation details,
 not stable public API.
 
@@ -173,6 +194,12 @@ not stable public API.
 
 **Rule:** no new parsing logic in KINETIC modules — call `LogseqGraph.load_directory` or `StackMachineParser`.
 
+LENS remains a compatible optional Parser adapter. Stage 0 marks it
+transitional and feature-frozen while preserving its commands and API without a
+deprecation warning. A later, separately accepted Matryca Trama migration owns
+user-facing graph-intelligence UI; removal or behavior change requires its own
+compatibility decision.
+
 ### `synapse.py` + `synapse_embed.py` — SYNAPSE adapters
 
 | Area | Responsibility |

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/COOKBOOK.md

@@ -204,6 +204,13 @@ visualizer.export_html(output)
 
 `export_html()` writes the HTML file but does not open it automatically.
 
+LENS is transitional and feature-frozen for this reference-topology workflow.
+`GraphVisualizer`, this recipe, `matryca-parse visualize`, and
+`matryca-parse demo` remain compatible and emit no deprecation warning in Stage
+0. Matryca Trama is the destination for future user-facing graph intelligence;
+a separately reviewed migration must provide compatibility guidance before any
+behavior change.
+
 ---
 
 ## Recipe 7 — Contributor test patterns

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/GOOD_FIRST_ISSUES.md

@@ -154,7 +154,7 @@ Run `make vendor-name-check` before docs PRs to ensure Ghost Tooling policy (no
 ## Out of scope for a first PR
 
 - Changes to Pydantic models in `logos_core.py` (open a design issue first).
-- Desktop GUI ([#3](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)) — multi-sprint epic.
+- Trama graph-intelligence UI ([#3](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)) — cross-product work; Parser LENS remains compatible and no Parser GUI work belongs in a first PR.
 - Bulk mldoc parity work in `logos_parser.py` — high regression risk.
 - Obsidian namespace path alignment — cross-tool behavior, needs design.
 

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/README.md

@@ -65,6 +65,7 @@ entry points.
 | [`reference/CONFORMANCE_SUPPORT_MATRIX.md`](reference/CONFORMANCE_SUPPORT_MATRIX.md) | Integrators, contributors | Supported runtimes, public contract tiers, optional adapters, and deprecation rules |
 | [`reference/DEPENDENCY_LICENSE_POLICY.md`](reference/DEPENDENCY_LICENSE_POLICY.md) | Maintainers, release reviewers | Release SBOM, dependency/license inventory, checksum, override, and attestation contract |
 | [`security/DAILY_METRICS_THREAT_MODEL.md`](security/DAILY_METRICS_THREAT_MODEL.md) | Maintainers, security reviewers | Trust boundaries and fail-closed controls for the self-mutating metrics archive |
+| [`security/DEPENDENCY_ADVISORY_EXCEPTIONS.md`](security/DEPENDENCY_ADVISORY_EXCEPTIONS.md) | Maintainers, security reviewers | Exact, time-bounded dependency advisory exceptions and compensating controls |
 | [`decisions/ADR-0001-PROTOCOL_ADAPTER_BOUNDARY.md`](decisions/ADR-0001-PROTOCOL_ADAPTER_BOUNDARY.md) | Maintainers, integrators | Decision to defer protocol endpoints until explicit safety and compatibility gates are met |
 | [`decisions/ADR-0002-OFFICIAL-OKF-V02-MIGRATION-GATE.md`](decisions/ADR-0002-OFFICIAL-OKF-V02-MIGRATION-GATE.md) | Maintainers, documentation reviewers | Decision to preserve the measured official OKF backlog until profile conflicts are resolved |
 | [`decisions/ADR-0003-AAIF-SUBMISSION-GATE.md`](decisions/ADR-0003-AAIF-SUBMISSION-GATE.md) | Maintainers, legal reviewers | Evidence-based NO-GO and reconsideration gate for any AAIF submission |

logseq_matryca_parser-1.9.0/docs/decisions/ADR-0004-PARSER-PLUMBER-BOUNDARY.md

@@ -0,0 +1,81 @@
+---
+type: ArchitectureDecision
+title: ADR-0004 Parser and Plumber boundary
+description: Decision that Parser remains a deterministic OG parsing library while Plumber owns the cross-product Logseq gateway.
+status: stable
+classification: active
+audience: maintainers
+owner: logseq-matryca-parser
+authority: source_repository
+execution_mode: reviewed
+last_verified: 2026-09-05
+verified: 2026-09-05
+stale_after: 2027-03-04
+okf_profile: matryca_okf_inspired_quality
+okf_spec_version: null
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0004: Parser and Plumber boundary
+
+## Status
+
+Accepted.
+
+## Context
+
+Logseq Matryca Parser already provides deterministic parsing of Logseq OG
+Markdown into a typed AST, an in-memory graph, and parser-native
+serializations. Cross-product integration needs one gateway that can select a
+source, own host adapters and session lifecycle, and publish stable contracts
+to product consumers without making those consumers depend on Parser internals.
+
+## Decision
+
+The supported OG data flow is:
+
+```text
+Logseq OG -> Parser -> Plumber -> Trama/Brain
+```
+
+Parser owns deterministic OG parsing, typed AST construction, its in-memory
+graph, and parser-native serialization. It accepts caller-provided local
+Markdown inputs, but does not choose a cross-product source, operate a Logseq
+host adapter, own sessions, or define public `plumber.*` contracts.
+
+Plumber owns source selection, Logseq host adapters, session lifecycle, and
+versioned public contracts for downstream consumers. The data flow above is not
+a Python dependency direction. The Parser runtime must not import Plumber, Trama, or Brain. Plumber may use Parser internally for an OG source.
+
+Trama and Brain consume Plumber contracts. They must not import or know Parser,
+and must not access Logseq OG files or a Logseq DB through a parallel gateway.
+
+LENS remains compatible in this slice. Its current API, CLI command, optional
+dependency, and behavior are unchanged. A later, separately reviewed migration
+will move user-facing graph-intelligence visualization to Trama and may begin a
+compatible LENS deprecation. This decision adds no warning, removal, command,
+or API change.
+
+Parser remains protocol-neutral under
+[ADR-0001](ADR-0001-PROTOCOL_ADAPTER_BOUNDARY.md). This decision adds no MCP
+server, network endpoint, GUI, release, or compatibility claim.
+
+## Consequences
+
+- Parser remains independently useful to developer consumers that need only
+  deterministic Markdown parsing, an in-memory graph, CLI workflows, or
+  parser-native exports.
+- Plumber is the only cross-product boundary between Logseq sources and Trama
+  or Brain.
+- Existing Parser public APIs and LENS compatibility promises remain unchanged.
+- Any future UI migration, host adapter, protocol, mutation, or release needs
+  its own accepted design and verification evidence.
+
+## Verification and rollback
+
+`tests/test_plumber_boundary_docs.py` keeps this decision and the maintained
+architecture guides explicit. `tests/test_layer_boundary.py` rejects Parser
+runtime imports of Plumber, Trama, and Brain. Rollback requires a superseding
+ADR and a separately reviewed compatibility plan; it does not authorize an
+implicit import or product-surface change.

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/decisions/index.md

@@ -15,6 +15,7 @@ introduced incrementally. Do not rewrite historical roadmaps into ADRs.
 | Privacy-safe local graph assurance | [`ADR-002-local-graph-assurance-boundary.md`](ADR-002-local-graph-assurance-boundary.md) | Accepted M5 aggregate-only local CLI boundary; no content retention or network operation |
 | Documentation lifecycle and MKQ | [`DOCUMENTATION_SYSTEM.md`](../DOCUMENTATION_SYSTEM.md) | Source contract recorded; MKQ-4 enforcement and private profile activation pending under issue #109 |
 | Protocol adapter boundary | [`ADR-0001-PROTOCOL_ADAPTER_BOUNDARY.md`](ADR-0001-PROTOCOL_ADAPTER_BOUNDARY.md) | Accepted: keep the core protocol-neutral until explicit schema, safety, permissions, and conformance gates are met |
+| Parser and Plumber boundary | [`ADR-0004-PARSER-PLUMBER-BOUNDARY.md`](ADR-0004-PARSER-PLUMBER-BOUNDARY.md) | Accepted: Parser owns deterministic OG parsing; Plumber is the sole cross-product Logseq gateway to Trama and Brain |
 | Official OKF v0.2 migration | [`ADR-0002-OFFICIAL-OKF-V02-MIGRATION-GATE.md`](ADR-0002-OFFICIAL-OKF-V02-MIGRATION-GATE.md) | Accepted: defer conformance while the measured 38-finding backlog and nested-index profile conflict remain |
 | AAIF submission | [`ADR-0003-AAIF-SUBMISSION-GATE.md`](ADR-0003-AAIF-SUBMISSION-GATE.md) | Accepted: NO-GO until governance, adoption, legal, live security, and release-evidence gates pass |
 

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/index.md

@@ -38,6 +38,7 @@ navigation layers only.
 | [Support and compatibility matrix](reference/CONFORMANCE_SUPPORT_MATRIX.md) | Supported runtimes, public API tiers, optional adapters, and explicit limits |
 | [Dependency, license, SBOM, and provenance policy](reference/DEPENDENCY_LICENSE_POLICY.md) | Release evidence, override, checksum, and attestation contract |
 | [Daily metrics threat model](security/DAILY_METRICS_THREAT_MODEL.md) | Security boundary for the self-mutating repository traffic archive |
+| [Dependency advisory exceptions](security/DEPENDENCY_ADVISORY_EXCEPTIONS.md) | Exact, time-bounded security audit exceptions and compensating controls |
 | [Architecture](CLEAN_CODE_ARCHITECTURE.md) | Canonical architecture and public graph API |
 | [Stellar audit baseline](REPOSITORY_STELLAR_ROADMAP_2026-08-06.md) | Dated evidence-backed audit and original improvement sequence |
 | [GitHub and AAIF readiness study](REPOSITORY_GOVERNANCE_AAIF_STUDY_2026-08-19.md) | Governance, supply-chain, agent, and AAIF-readiness study |

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/log.md

@@ -19,6 +19,21 @@ superseded_by: null
 
 # Documentation evolution log
 
+## 2026-08-30 — v1.8.2 publication
+
+- Published v1.8.2 from PR #198 merge SHA
+  `976d5413df27330226d9b3a65b005d129de236b0` at tag `v1.8.2`.
+- Release workflow run [#33295184723](https://github.com/MarcoPorcellato/logseq-matryca-parser/actions/runs/33295184723) completed successfully, creating the [GitHub Release](https://github.com/MarcoPorcellato/logseq-matryca-parser/releases/tag/v1.8.2) and [PyPI 1.8.2](https://pypi.org/project/logseq-matryca-parser/1.8.2/) publication.
+- Downloaded release assets matched `SHA256SUMS`, and GitHub attestation
+  verification passed for every listed artifact against this repository:
+
+  | Artifact | SHA-256 | Attestation |
+  | --- | --- | --- |
+  | `logseq_matryca_parser-1.8.2-py3-none-any.whl` | `1b3deb43466c63c46ca3b11cd35a2b4436b0ba3528a5f82bcc52fd0a10cd4820` | Verified |
+  | `logseq_matryca_parser-1.8.2.tar.gz` | `aa9a15ab43c1197724550fde121023da52d4ade49f9886eaa0c48df04c37be08` | Verified |
+  | `SBOM.cdx.json` | `67802e45427a76f0de1bd9ce544eb5199ac48aa00611fca807b5d5fd01c131e0` | Verified |
+  | `DEPENDENCY_LICENSES.json` | `fb75132dd4562d8b25dd8dda45ef41ff0fe64a7966d6967cd859071802f20834` | Verified |
+
 ## 2026-08-30 — v1.8.2 release candidate
 
 - Prepared the v1.8.2 release candidate from

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/maintained.toml

@@ -38,6 +38,7 @@ maintained_documents = [
   "docs/decisions/ADR-0001-PROTOCOL_ADAPTER_BOUNDARY.md",
   "docs/decisions/ADR-0002-OFFICIAL-OKF-V02-MIGRATION-GATE.md",
   "docs/decisions/ADR-0003-AAIF-SUBMISSION-GATE.md",
+  "docs/decisions/ADR-0004-PARSER-PLUMBER-BOUNDARY.md",
   "docs/decisions/ADR-001-external-oracle-boundary.md",
   "docs/decisions/ADR-002-local-graph-assurance-boundary.md",
   "docs/reference/index.md",
@@ -48,6 +49,7 @@ maintained_documents = [
   "docs/reference/DIAGNOSTICS.md",
   "docs/reference/FILESYSTEM_SAFETY.md",
    "docs/security/DAILY_METRICS_THREAT_MODEL.md",
+   "docs/security/DEPENDENCY_ADVISORY_EXCEPTIONS.md",
    "docs/reference/LOCAL_GRAPH_ASSURANCE.md",
    "docs/reference/PERFORMANCE_EVIDENCE.md",
    "docs/rfc/SOURCE_LOCATION_RFC.md",

{logseq_matryca_parser-1.8.2 → logseq_matryca_parser-1.9.0}/docs/reference/API_STABILITY.md

@@ -8,8 +8,8 @@ audience: contributors
 owner: logseq-matryca-parser
 authority: source_repository
 execution_mode: reviewed
-last_verified: 2026-08-07
-verified: 2026-08-07
+last_verified: 2026-09-05
+verified: 2026-09-05
 stale_after: 2027-02-03
 okf_profile: matryca_okf_inspired_quality
 okf_spec_version: null
@@ -40,7 +40,7 @@ minor release unless a security issue makes that unsafe.
 |---|---|
 | Version | `__version__` |
 | Parser | `StackMachineParser`, `LogosParser`, `LogseqPage`, `LogseqNode`, `LogosNode`, `ASTVisitor` |
-| Graph | `LogseqGraph` |
+| Graph | `LogseqGraph`, `SnapshotPage` |
 | Diagnostics | `Diagnostic`, `DiagnosticCode`, `DiagnosticSeverity`, `collect_graph_diagnostics` |
 | Errors | `LogseqParserError`, `LogseqIndentationError`, `BlockReferenceError`, `PageTitleCollisionError`, `VaultWriteError` |
 | Writer preview | `WriteProposal` |
@@ -57,6 +57,19 @@ the loader normalizes a textual path with `Path(graph_path).expanduser().resolve
 Both strict modes are opt-in, preserving the
 permissive default.
 
+`SnapshotPage(logical_path, text)` and
+`LogseqGraph.from_snapshot_pages(graph_path, snapshot_pages, *, strict_refs=False,
+strict_title_collisions=False)` are stable additive graph APIs. The factory accepts
+either a mapping of graph-relative POSIX Markdown paths to already-captured text or
+a sequence of `SnapshotPage` values. It normalizes and orders unique `pages/` and
+`journals/` paths deterministically, accepts at most 1,024 pages and 16 MiB of UTF-8
+text, parses with the existing in-memory parser, and reuses the ordinary graph index
+builders and strict modes. It never discovers or reopens logical source paths.
+Synthetic source paths on the resulting models are metadata for graph behavior, not
+filesystem-read authority; capture, source selection, hashing, and revisions remain
+the caller's responsibility. Its graph-root label is normalized lexically without
+expanding, resolving, or inspecting the caller path.
+
 Diagnostic code compatibility, serialization, and path-safety rules are defined
 in the [structured diagnostics contract](DIAGNOSTICS.md).
 Vault-bound writer and asset-read guarantees are defined in the
@@ -78,6 +91,12 @@ The following integrations remain public but experimental:
 Everything not exported from `logseq_matryca_parser.__all__` is internal unless
 another maintained contract explicitly promotes it.
 
+`GraphVisualizer` remains experimental, compatible, transitional, and
+feature-frozen in this release line. Stage 0 changes no API and emits no
+deprecation warning. Future user-facing graph intelligence belongs in Matryca
+Trama; a compatible deprecation may begin only through a separately reviewed
+decision, release notes, and migration guidance.
+
 ## Version source
 
 `src/logseq_matryca_parser/_version.py` is the single authoritative version