logseq-matryca-parser 1.2.2__tar.gz → 1.3.0__tar.gz

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-06-19
+
+### Changed
+
+- **Sprint 1 architectural quick wins** — **`discover_graph_files`** moved from `kinetic.py` to `logseq_paths.py` (decouples CLI from `LogseqGraph`); KINETIC optional-dependency errors now recommend **`uv sync --extra ai|viz`**; **`lens.py`** lazy-imports NetworkX/PyVis; **SYNAPSE** exports vector-store-safe metadata via **`SynapseMetadata`** / **`build_synapse_metadata`** (`task_priority`, temporal epochs, `source_uuid`, joined `path`/`refs`); explicit **`[tool.ruff]`** config in `pyproject.toml`.
+- **Sprint 2 runtime robustness** — **`LogseqGraphWatcher`** debounces filesystem events (~500ms) and ignores editor temp/swap files; **`StackMachineParser(strict_refs=True)`** raises **`BlockReferenceError`** for unresolved same-page `((uuid))` refs (default off); **KINETIC** adds **`@app.callback()`** with **`--verbose`** / **`--graph`**, **`rich_markup_mode="rich"`**, and shared graph-path resolution.
+- **Sprint 3 architecture** — **`LogseqGraph`** uses **`validate_assignment=True`** (no frozen/`object.__setattr__` hack); **SYNAPSE** **`LlamaIndexVisitor`** adds **`SOURCE`**, **`NEXT`**, and **`PREVIOUS`** relationships; package root **`__init__.py`** exports **`SynapseAdapter`**, **`SessionAliasRegistry`**, **`GraphVisualizer`**, and core LOGOS symbols via explicit **`__all__`**.
+- **Optional AI stack** — `llama-index-core` bumped to `0.14.22` via lock refresh.
+- **Documentation** — README, ARCHITECTURE, CONTRIBUTING, SECURITY, CODEQL, AST primer, and roadmaps updated for **1.3.0** (public API, watcher debounce, `strict_refs`, LlamaIndex spatial edges, `uv` install).
+
+### Security
+
+- **Transitive dependency hardening** — `uv` constraints pin `aiohttp>=3.14.1` (11 Dependabot alerts); `nltk` overridden to `v3.10.0-rc1` from upstream Git until NLTK 3.10.0 ships on PyPI (GHSA-p4gq-832x-fm9v). Affects optional `[ai]` / `[all]` extras only; core install unchanged.
+
 ## [1.2.2] - 2026-06-18
 
 ### Fixed

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ User-facing behavior is documented in:
 - [`README.md`](README.md) — overview, quickstart, and feature matrix
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — LOGOS, SYNAPSE, `LogseqGraph`, agents, and data flow
 - [`docs/logseq_ast_primer.md`](docs/logseq_ast_primer.md) — Logseq Spatial Markdown domain rules
-- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.2.2**) and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.3.0**) and **Unreleased** changes (Keep a Changelog)
 - [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) — version bump, tag, and PyPI publish checklist
 - [`docs/CODEQL.md`](docs/CODEQL.md) — CodeQL default setup (no custom `codeql.yml`)
 

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.2.2
+Version: 1.3.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
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
 [![Status: Stable](https://img.shields.io/badge/Status-Stable-22c55e.svg?style=flat-square)](#)
 ![Origin: Matryca.ai](https://img.shields.io/badge/Origin-Matryca.ai-gold?style=for-the-badge)
 
-**v1.2.2** — CodeQL CI fix & docs (see [CHANGELOG](CHANGELOG.md)) — **234 tests**, no parser API changes; SAST via GitHub CodeQL **default setup** ([`docs/CODEQL.md`](docs/CODEQL.md)).
+**v1.3.0** — Architecture & runtime hardening (see [CHANGELOG](CHANGELOG.md)) — **244 tests**, public API exports, watcher debounce, `strict_refs`, LlamaIndex spatial edges; SAST via GitHub CodeQL **default setup** ([`docs/CODEQL.md`](docs/CODEQL.md)).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -147,6 +147,23 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ Release highlights (v1.3.0)
+
+Minor release — architectural quick wins, runtime robustness, and expanded public API. No breaking changes to default parser behavior.
+
+| Area | Change |
+| :--- | :--- |
+| **Public API** | Root **`logseq_matryca_parser`** exports **`SynapseAdapter`**, **`SessionAliasRegistry`**, **`GraphVisualizer`**, **`discover_graph_files`**, and core LOGOS symbols via explicit **`__all__`**. |
+| **Graph model** | **`LogseqGraph`** uses **`validate_assignment=True`** instead of frozen/`object.__setattr__` for incremental reloads. |
+| **Live watcher** | **`start_watching()`** debounces filesystem events (~500ms) and ignores editor temp/swap files (`.swp`, `~`, `.tmp`, `.DS_Store`). |
+| **Strict refs** | **`StackMachineParser(strict_refs=True)`** raises **`BlockReferenceError`** for unresolved same-page `((uuid))` refs (default off). |
+| **SYNAPSE** | **`SynapseMetadata`** / **`build_synapse_metadata`** for vector-store-safe fields; **LlamaIndex** adds **`SOURCE`**, **`NEXT`**, **`PREVIOUS`** relationships. |
+| **KINETIC CLI** | Global **`--verbose`** / **`--graph`** via **`@app.callback()`**; optional-dependency hints recommend **`uv sync --extra ai\|viz`**. |
+| **LENS** | Lazy-imports NetworkX/PyVis so core installs stay lightweight. |
+| **Security** | Transitive **`aiohttp`** / **`nltk`** constraints for optional **`[ai]`** extras. |
+
+---
+
 ## ⚡ Release highlights (v1.2.2)
 
 Patch release — fixes a failing CodeQL GitHub Actions workflow; **no parser or public API changes**.
@@ -236,7 +253,7 @@ matryca-parse export /path/to/logseq/graph /path/to/obsidian/vault --format obsi
 > **Note:** Wikilinks currently use the **Logseq page title** (e.g. `[[Target#^…]]`). Vault files may live under namespace folders (`Projects/AI/Demo.md`). Obsidian usually resolves unique titles; aligning link text to folder paths is a possible future refinement.
 
 ### Live incremental watcher
-`LogseqGraph` supports **surgical file invalidation** (optional dependency: `pip install 'logseq-matryca-parser[watch]'`). `start_watching()` runs a recursive **watchdog** observer: on `created` / `modified` under `pages/` or `journals/`, only that file is re-parsed; stale synthetic UUIDs are purged from `_node_registry` and scrubbed from `_backlink_registry`—no full-graph cold reload.
+`LogseqGraph` supports **surgical file invalidation** (optional dependency: `uv sync --extra watch`). `start_watching()` runs a recursive **watchdog** observer with **~500ms debounce** and ignores editor temp/swap files: on `created` / `modified` under `pages/` or `journals/`, only that file is re-parsed; stale synthetic UUIDs are purged from `_node_registry` and scrubbed from `_backlink_registry`—no full-graph cold reload.
 
 ### Fluent topological queries
 Filter the global node registry with a **chainable** API (tags, task state, ancestry under a parent UUID):
@@ -315,12 +332,17 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.2.2)
-pip install logseq-matryca-parser
+# Install from PyPI (latest: v1.3.0)
+uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates
-pip install 'logseq-matryca-parser[watch]'
+uv pip install 'logseq-matryca-parser[watch]'
+
+# Or clone and sync all extras locally
+uv sync --all-extras
+```
 
+```bash
 # 1. Visualize your local graph (LENS)
 matryca-parse visualize /path/to/logseq/graph my-map.html
 
@@ -332,13 +354,23 @@ matryca-parse export /path/to/logseq/graph output --format langchain-enriched
 
 # 4. Obsidian vault (YAML frontmatter + ^ block ids)
 matryca-parse export /path/to/logseq/graph output --format obsidian
+
+# Global options (all subcommands): --verbose, --graph /path/to/vault
+matryca-parse --graph /path/to/logseq/graph --verbose export output --format json
 ```
 
 ### Python API
+
+Prefer the package root for stable imports (see **`__all__`** in **`logseq_matryca_parser`**):
+
 ```python
-from logseq_matryca_parser.graph import LogseqGraph
-from logseq_matryca_parser.logos_parser import LogosParser
-from logseq_matryca_parser.synapse import SynapseAdapter
+from logseq_matryca_parser import (
+    LogseqGraph,
+    LogosParser,
+    SynapseAdapter,
+    SessionAliasRegistry,
+    discover_graph_files,
+)
 
 # Parse a single page to AST (YAML or native frontmatter; utf-8-sig BOM-safe)
 page = LogosParser().parse_page_file("page.md")
@@ -352,6 +384,11 @@ effective = graph.get_effective_properties(page_obj.root_nodes[0].uuid)
 
 # Export to LangChain with lineage metadata
 docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
+
+# Optional strict same-page block-ref validation at parse time
+from logseq_matryca_parser import StackMachineParser
+
+strict_page = StackMachineParser(strict_refs=True).parse_page_file("page.md")
 ```
 
 ### 🤖 Agentic Write Access (Append-Only)

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/README.md

@@ -12,7 +12,7 @@
 [![Status: Stable](https://img.shields.io/badge/Status-Stable-22c55e.svg?style=flat-square)](#)
 ![Origin: Matryca.ai](https://img.shields.io/badge/Origin-Matryca.ai-gold?style=for-the-badge)
 
-**v1.2.2** — CodeQL CI fix & docs (see [CHANGELOG](CHANGELOG.md)) — **234 tests**, no parser API changes; SAST via GitHub CodeQL **default setup** ([`docs/CODEQL.md`](docs/CODEQL.md)).
+**v1.3.0** — Architecture & runtime hardening (see [CHANGELOG](CHANGELOG.md)) — **244 tests**, public API exports, watcher debounce, `strict_refs`, LlamaIndex spatial edges; SAST via GitHub CodeQL **default setup** ([`docs/CODEQL.md`](docs/CODEQL.md)).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -106,6 +106,23 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ Release highlights (v1.3.0)
+
+Minor release — architectural quick wins, runtime robustness, and expanded public API. No breaking changes to default parser behavior.
+
+| Area | Change |
+| :--- | :--- |
+| **Public API** | Root **`logseq_matryca_parser`** exports **`SynapseAdapter`**, **`SessionAliasRegistry`**, **`GraphVisualizer`**, **`discover_graph_files`**, and core LOGOS symbols via explicit **`__all__`**. |
+| **Graph model** | **`LogseqGraph`** uses **`validate_assignment=True`** instead of frozen/`object.__setattr__` for incremental reloads. |
+| **Live watcher** | **`start_watching()`** debounces filesystem events (~500ms) and ignores editor temp/swap files (`.swp`, `~`, `.tmp`, `.DS_Store`). |
+| **Strict refs** | **`StackMachineParser(strict_refs=True)`** raises **`BlockReferenceError`** for unresolved same-page `((uuid))` refs (default off). |
+| **SYNAPSE** | **`SynapseMetadata`** / **`build_synapse_metadata`** for vector-store-safe fields; **LlamaIndex** adds **`SOURCE`**, **`NEXT`**, **`PREVIOUS`** relationships. |
+| **KINETIC CLI** | Global **`--verbose`** / **`--graph`** via **`@app.callback()`**; optional-dependency hints recommend **`uv sync --extra ai\|viz`**. |
+| **LENS** | Lazy-imports NetworkX/PyVis so core installs stay lightweight. |
+| **Security** | Transitive **`aiohttp`** / **`nltk`** constraints for optional **`[ai]`** extras. |
+
+---
+
 ## ⚡ Release highlights (v1.2.2)
 
 Patch release — fixes a failing CodeQL GitHub Actions workflow; **no parser or public API changes**.
@@ -195,7 +212,7 @@ matryca-parse export /path/to/logseq/graph /path/to/obsidian/vault --format obsi
 > **Note:** Wikilinks currently use the **Logseq page title** (e.g. `[[Target#^…]]`). Vault files may live under namespace folders (`Projects/AI/Demo.md`). Obsidian usually resolves unique titles; aligning link text to folder paths is a possible future refinement.
 
 ### Live incremental watcher
-`LogseqGraph` supports **surgical file invalidation** (optional dependency: `pip install 'logseq-matryca-parser[watch]'`). `start_watching()` runs a recursive **watchdog** observer: on `created` / `modified` under `pages/` or `journals/`, only that file is re-parsed; stale synthetic UUIDs are purged from `_node_registry` and scrubbed from `_backlink_registry`—no full-graph cold reload.
+`LogseqGraph` supports **surgical file invalidation** (optional dependency: `uv sync --extra watch`). `start_watching()` runs a recursive **watchdog** observer with **~500ms debounce** and ignores editor temp/swap files: on `created` / `modified` under `pages/` or `journals/`, only that file is re-parsed; stale synthetic UUIDs are purged from `_node_registry` and scrubbed from `_backlink_registry`—no full-graph cold reload.
 
 ### Fluent topological queries
 Filter the global node registry with a **chainable** API (tags, task state, ancestry under a parent UUID):
@@ -274,12 +291,17 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.2.2)
-pip install logseq-matryca-parser
+# Install from PyPI (latest: v1.3.0)
+uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates
-pip install 'logseq-matryca-parser[watch]'
+uv pip install 'logseq-matryca-parser[watch]'
+
+# Or clone and sync all extras locally
+uv sync --all-extras
+```
 
+```bash
 # 1. Visualize your local graph (LENS)
 matryca-parse visualize /path/to/logseq/graph my-map.html
 
@@ -291,13 +313,23 @@ matryca-parse export /path/to/logseq/graph output --format langchain-enriched
 
 # 4. Obsidian vault (YAML frontmatter + ^ block ids)
 matryca-parse export /path/to/logseq/graph output --format obsidian
+
+# Global options (all subcommands): --verbose, --graph /path/to/vault
+matryca-parse --graph /path/to/logseq/graph --verbose export output --format json
 ```
 
 ### Python API
+
+Prefer the package root for stable imports (see **`__all__`** in **`logseq_matryca_parser`**):
+
 ```python
-from logseq_matryca_parser.graph import LogseqGraph
-from logseq_matryca_parser.logos_parser import LogosParser
-from logseq_matryca_parser.synapse import SynapseAdapter
+from logseq_matryca_parser import (
+    LogseqGraph,
+    LogosParser,
+    SynapseAdapter,
+    SessionAliasRegistry,
+    discover_graph_files,
+)
 
 # Parse a single page to AST (YAML or native frontmatter; utf-8-sig BOM-safe)
 page = LogosParser().parse_page_file("page.md")
@@ -311,6 +343,11 @@ effective = graph.get_effective_properties(page_obj.root_nodes[0].uuid)
 
 # Export to LangChain with lineage metadata
 docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
+
+# Optional strict same-page block-ref validation at parse time
+from logseq_matryca_parser import StackMachineParser
+
+strict_page = StackMachineParser(strict_refs=True).parse_page_file("page.md")
 ```
 
 ### 🤖 Agentic Write Access (Append-Only)

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/SECURITY.md

@@ -6,7 +6,7 @@ Security fixes are provided **only for the latest released version** on [PyPI](h
 
 | Version | Supported |
 | ------- | --------- |
-| **1.2.2** (latest) | Yes |
+| **1.3.0** (latest) | Yes |
 | Older releases | No |
 
 We recommend always running the current release and upgrading promptly when a security advisory is published.

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/docs/ARCHITECTURE.md

@@ -82,7 +82,7 @@ title Logseq Matryca Parser — C4 Level 2 (Containers)
 Person(knowledgeWorker, "Knowledge Worker", "Local operator of a sovereign Logseq graph.")
 
 System_Boundary(matrycaEcosystem, "Matryca.ai Ecosystem") {
-    Container(kinetic, "KINETIC", "Typer / Rich CLI", "CLI — export (json, markdown, langchain, langchain-enriched, obsidian), visualize, demo, graph scans, `agent-read` / `agent-write` (X-Ray + headless splice), weekly append (`append`).")
+    Container(kinetic, "KINETIC", "Typer / Rich CLI", "CLI — global `--verbose` / `--graph` callback; export (json, markdown, langchain, langchain-enriched, obsidian), visualize, demo, graph scans, `agent-read` / `agent-write` (X-Ray + headless splice), weekly append (`append`).")
     Container(logos, "LOGOS", "Python / Pydantic", "Stack-Machine AST engine — LogseqPage and LogseqNode models.")
     Container(synapse, "SYNAPSE", "LangChain / LlamaIndex", "Framework-native exporters with parent-child metadata.")
     Container(lens, "LENS", "NetworkX / PyVis", "Reference-topology visualization to interactive HTML.")
@@ -258,7 +258,9 @@ classDiagram
 
 - **LangChain.** [`LangChainVisitor`](../src/logseq_matryca_parser/synapse.py) emits one **`Document`** per node with `page_content=node.clean_text` and metadata unioning **`node.properties`** with lineage fields (`uuid`, `parent_id`, `indent_level`, `source`, **`path`** — the UUID ancestry chain — `left_id`, `refs`, `task_status`, repeater, `created_at`). The underlying **`LogseqNode`** additionally carries **`task_priority`**, **`scheduled_at`**, and **`deadline_at`** (§3.1); adapters or custom visitors can project those into metadata when feeding **downstream graph databases** or **GraphRAG** filters. This preserves **parent context** explicitly in retrieval filters and re-ranking.
 
-- **LlamaIndex.** [`LlamaIndexVisitor`](../src/logseq_matryca_parser/synapse.py) constructs **`TextNode`** instances keyed by **`id_=node.uuid`**. It wires **`NodeRelationship.PARENT`** and **`CHILD`** via **`RelatedNodeInfo`**, back-linking when the parent appears earlier in preorder traversal — encoding **topology as first-class edges** beyond flat metadata dictionaries.
+- **LlamaIndex.** [`LlamaIndexVisitor`](../src/logseq_matryca_parser/synapse.py) constructs **`TextNode`** instances keyed by **`id_=node.uuid`**. It wires **`NodeRelationship.PARENT`** and **`CHILD`** via **`RelatedNodeInfo`**, back-linking when the parent appears earlier in preorder traversal — encoding **topology as first-class edges** beyond flat metadata dictionaries. From **v1.3.0**, it also emits **`SOURCE`** (page-level anchor via **`page_source_node_id`**), **`NEXT`**, and **`PREVIOUS`** sibling edges for spatial traversal in vector stores.
+
+- **Vector-store metadata.** **`SynapseMetadata`** and **`build_synapse_metadata`** project **`task_priority`**, temporal epoch fields, **`source_uuid`**, and joined **`path`** / **`refs`** strings into LangChain/LlamaIndex metadata without leaking raw Python list reprs.
 
 Together, adapters guarantee that **embedding units align with intentional block boundaries**, not splitter accidents.
 
@@ -276,7 +278,7 @@ The KINETIC **`export --format langchain-enriched`** path serializes these docum
 
 ### 3.3 LENS — NetworkX topology + PyVis interactive visualization
 
-**LENS** (`logseq_matryca_parser.lens.GraphVisualizer`) builds a **`networkx.Graph`** over **page ⇄ wiki/tag reference** projections using `NetworkXVisitor` during AST preorder walks. Nodes receive **degree-based sizing** (“sun” hotspots) and subgroup classification (`page`, `tag`, `journal`, etc.).
+**LENS** (`logseq_matryca_parser.lens.GraphVisualizer`) builds a **`networkx.Graph`** over **page ⇄ wiki/tag reference** projections using `NetworkXVisitor` during AST preorder walks. Nodes receive **degree-based sizing** (“sun” hotspots) and subgroup classification (`page`, `tag`, `journal`, etc.). **NetworkX** and **PyVis** are **lazy-imported** (optional **`[viz]`** extra) so core installs avoid pulling visualization dependencies until `GraphVisualizer` is used.
 
 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**).
 
@@ -296,14 +298,14 @@ Both paths keep **existing topology intact** relative to their contract: append-
 
 ### 3.6 `LogseqGraph` — namespace scoping, O(1) invalidation, live watch
 
-The **in-memory graph** ([`graph.py`](../src/logseq_matryca_parser/graph.py)) is the runtime **RAM image** of the sovereign vault: `pages: dict[str, LogseqPage]`, a private **`_node_registry`** keyed by synthetic block UUID, and a **`_backlink_registry`** mapping normalized link targets to source node UUIDs.
+The **in-memory graph** ([`graph.py`](../src/logseq_matryca_parser/graph.py)) is the runtime **RAM image** of the sovereign vault: `pages: dict[str, LogseqPage]`, a private **`_node_registry`** keyed by synthetic block UUID, and a **`_backlink_registry`** mapping normalized link targets to source node UUIDs. **`LogseqGraph`** uses **`ConfigDict(strict=True, validate_assignment=True)`** (not frozen) so **`invalidate_and_reload_page`** can mutate registries and page maps without `object.__setattr__` workarounds.
 
 #### Page title overrides and alias indexing (`_enrich_pages_index`)
 
 After every bulk or incremental parse, the graph applies a **post-parse enrichment pass** before backlink construction:
 
 1. **Filename → canonical title.** Each markdown file is first keyed by **`derive_page_title_from_source_path`** (see §3.9).
-2. **`title::` override.** If page frontmatter contains a non-empty string **`title`**, the frozen `LogseqPage` is updated via **`model_copy(update={"title": custom})`**, the old filename key is removed from **`pages`**, and the page is re-inserted under the custom title (collision with another file’s title is skipped with a debug log).
+2. **`title::` override.** If page frontmatter contains a non-empty string **`title`**, the `LogseqPage` is updated via **`model_copy(update={"title": custom})`**, the old filename key is removed from **`pages`**, and the page is re-inserted under the custom title (collision with another file’s title is skipped with a debug log).
 3. **Alias injection.** For each canonical dict entry where **`dict_key == page.title`**, values from **`alias::`** and **`aliases::`** are normalized (comma-separated strings or Python lists; `[[Page]]` / `#tag` adornments stripped using the same rules as [`logseq_markdown.py`](../src/logseq_matryca_parser/logseq_markdown.py)) and registered as **additional keys** pointing at the **same `LogseqPage` instance** — e.g. `pages["Dev"]` and `pages["Development"]` share identity.
 4. **Backlinks.** **`_build_backlink_registry`** walks **unique pages** (`id(page)` deduplication) so alias keys do not double-count outgoing links. Incoming wikilinks such as **`[[Dev]]`** normalize to lowercase registry keys and resolve through **`get_backlinks("Dev")`** like any other page title.
 
@@ -341,7 +343,11 @@ This keeps **global indexes consistent** without rebuilding the entire graph —
 
 #### Live filesystem watcher (`start_watching`)
 
-**`LogseqGraph.start_watching(callback=None)`** (optional **`watchdog`** install) returns a **`LogseqGraphWatcher`** that schedules a recursive **`Observer`** on the graph root. **`on_modified` / `on_created`** events for tracked Markdown call **`invalidate_and_reload_page`**, then optionally invoke **`callback(path)`** — the intended hook for **vector store patch**, **re-embedding**, or UI refresh. Event routing ignores directories and non-tracked extensions so the hot path stays tight.
+**`LogseqGraph.start_watching(callback=None, debounce_seconds=0.5)`** (optional **`watchdog`** install) returns a **`LogseqGraphWatcher`** that schedules a recursive **`Observer`** on the graph root. **`on_modified` / `on_created`** events for tracked Markdown call **`invalidate_and_reload_page`**, then optionally invoke **`callback(path)`** — the intended hook for **vector store patch**, **re-embedding**, or UI refresh. **`_DebouncedGraphEventRouter`** coalesces rapid save bursts (~500ms default) and ignores editor temp/swap artifacts (`.swp`, `~`, `.tmp`, `.DS_Store`). Event routing ignores directories and non-tracked extensions so the hot path stays tight.
+
+#### Parse-time reference validation (`strict_refs`)
+
+**`StackMachineParser(..., strict_refs=False)`** (default) resolves same-page `((uuid))` block refs leniently. When **`strict_refs=True`**, unresolved refs raise **`BlockReferenceError`** at parse time — complementary to **`LogseqGraph.get_broken_references()`**, which scans the loaded graph post-hoc.
 
 #### Fluent topological queries (`GraphQuery`)
 
@@ -404,6 +410,8 @@ The compound CLI commands **`agent_read`** and **`agent_write`** in [`kinetic.py
 
 Rich styling injects **ANSI escape sequences** that waste tokens and can cause models to **hallucinate markup** as content. `agent-read` is **stdout-pure** so shell pipelines, MCP tools, and headless agents receive **unescaped plain text** only. Human-oriented commands (`scan`, `export`, `visualize`) keep Rich; the **machine-native read/write paths** opt out where token fidelity matters.
 
+**Global CLI options (v1.3.0).** [`kinetic.py`](../src/logseq_matryca_parser/kinetic.py) registers **`@app.callback()`** with **`--verbose`** and **`--graph`** so every subcommand shares graph-path resolution and debug logging. Optional extras (`[ai]`, `[viz]`) print **`uv sync --extra …`** hints on import failure.
+
 This complements §3.4 **AGENT WRITER** (weekly append + headless splice) and §3.2 **SYNAPSE** (human/RAG chunking): one stack, multiple projections — **enriched chunks for vectors**, **X-Ray + alias state for agent context**, **append / splice for durable writes**.
 
 ### 3.8 Bidirectional I/O and Logseq Layouts
@@ -459,7 +467,7 @@ Logseq namespaces use **`/`** in titles (e.g. `Projects/AI`). On disk, each segm
 
 #### Graph discovery filters
 
-When scanning a vault root, **`is_excluded_graph_path`** drops noise directories — notably **`.recycle`**, **`.git`**, and the internal **`logseq`** config tree — so incremental watchers and bulk loaders never ingest backup blobs or VCS metadata as pages. This keeps **`LogseqGraph.load_directory`** and **`invalidate_and_reload_page`** focused on sovereign content under `pages/` and `journals/`.
+When scanning a vault root, **`discover_graph_files`** (in [`logseq_paths.py`](../src/logseq_matryca_parser/logseq_paths.py), shared by **`LogseqGraph.load_directory`** and **KINETIC**) enumerates `pages/` and `journals/` markdown. **`is_excluded_graph_path`** drops noise directories — notably **`.recycle`**, **`.git`**, and the internal **`logseq`** config tree — so incremental watchers and bulk loaders never ingest backup blobs or VCS metadata as pages. This keeps **`LogseqGraph.load_directory`** and **`invalidate_and_reload_page`** focused on sovereign content under `pages/` and `journals/`.
 
 ---
 
@@ -528,4 +536,4 @@ Recursive and character-budget chunkers assume **approximately flat prose**. Log
 
 ---
 
-*This document reflects the implementations in `src/logseq_matryca_parser/logos_parser.py`, `synapse.py`, `graph.py`, `forge.py`, `lens.py`, `logos_core.py`, `agent_writer.py`, `agent_press.py`, `logseq_markdown.py`, and `logseq_paths.py`, and complements narrative primers such as [`logseq_ast_primer.md`](logseq_ast_primer.md).* 
+*This document reflects the implementations in `src/logseq_matryca_parser/logos_parser.py`, `synapse.py`, `graph.py`, `forge.py`, `lens.py`, `logos_core.py`, `agent_writer.py`, `agent_press.py`, `logseq_markdown.py`, `logseq_paths.py`, `kinetic.py`, and the public exports in `__init__.py`, and complements narrative primers such as [`logseq_ast_primer.md`](logseq_ast_primer.md).* 

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/docs/CODEQL.md

@@ -1,6 +1,6 @@
 # CodeQL code scanning
 
-**Logseq Matryca Parser** (v1.2.2+) uses **GitHub CodeQL default setup** for static analysis (SAST) on Python.
+**Logseq Matryca Parser** (v1.3.0+) uses **GitHub CodeQL default setup** for static analysis (SAST) on Python.
 
 ## Why there is no `codeql.yml` workflow
 

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/docs/logseq_ast_primer.md

@@ -214,4 +214,4 @@ If you feed Logseq Markdown into `RecursiveCharacterTextSplitter` (LangChain) or
 
 The **Logos Protocol** solves this by walking the AST deterministically, isolating properties, shielding dead-zone literals, and using the `SYNAPSE` adapter to export native LangChain `Document` or LlamaIndex `TextNode` objects. Every generated object retains its exact hierarchical lineage in the metadata, feeding your local LLM perfectly structured data.
 
-For vault-wide navigation (aliases, backlinks, namespace shadowing, assets), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (graph parity from **v1.2.0**; **v1.2.1** adds CI/OSS hardening; **v1.2.2** fixes CodeQL CI and documents default setup).
+For vault-wide navigation (aliases, backlinks, namespace shadowing, assets), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (graph parity from **v1.2.0**; **v1.3.0** adds watcher debounce, `strict_refs`, public API exports, and LlamaIndex spatial relationships).

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/docs/roadmaps/ROADMAP_INCREMENTAL_WATCHER.md

@@ -1,5 +1,7 @@
 # 📜 Architectural Contract: Live Incremental Invalidation & File Watcher
 **Contract Status:** Wave 7 — Implemented (incremental invalidation + lazy watchdog watcher)
+
+> **Implementation note (v1.3.0):** `LogseqGraph` now uses `validate_assignment=True` (not `frozen=True`); the watcher debounces events (~500ms) and ignores editor temp files. Historical spec text below describes the original contract.
 **Target Stack:** Python 3.12+ | Pydantic V2 | Watchdog (Optional/Lazy Dependency)
 **Inspiration Architectures:**
 - `Microsoft/language-server-protocol` (Incremental text document synchronization and dependency invalidation)

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/docs/roadmaps/ROADMAP_UUID_AND_GRAPH_SUPERPOWERS.md

@@ -1,5 +1,7 @@
 # 📜 Architectural Contract: Synthetic UUID Hardening & Graph Orchestration Module
 **Contract Status:** Completed (Autonomous Execution)
+
+> **Implementation note (v1.3.0):** `discover_graph_files` lives in `logseq_paths.py` (not `kinetic.py`); `LogseqGraph` uses `validate_assignment=True` instead of `frozen=True`. Historical spec text below describes the original contract.
 **Target Stack:** Python 3.12+ | Pydantic V2 (Strict/Frozen Models) | Local-First No-DB
 
 **Execution checklist**

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/examples/run_demo.py

@@ -11,10 +11,11 @@ root_dir = Path(__file__).parent.parent
 sys.path.append(str(root_dir / "src"))
 
 try:
-    from logseq_matryca_parser.logos_parser import LogosParser
-    from logseq_matryca_parser.forge import ForgeExporter
     from rich.console import Console
     from rich.panel import Panel
+
+    from logseq_matryca_parser.forge import ForgeExporter
+    from logseq_matryca_parser.logos_parser import LogosParser
 except ImportError as e:
     print(f"Errore: Assicurati di aver installato le dipendenze (pip install rich typer pydantic). {e}")
     sys.exit(1)

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/legacy/local_digestor.py

@@ -5,10 +5,9 @@ import re
 import shutil
 import urllib.request
 from datetime import datetime
-from typing import Any, Dict, Literal, TypeVar
+from typing import Any, Literal, TypeVar
 
 from pydantic import BaseModel, ValidationError
-
 from smart_router.core.ingestion_engine import IngestionEngine
 from smart_router.core.librarian_models import (
     EntityNodeSchema,
@@ -31,7 +30,7 @@ async def emit_note_package(
     slug: str,
     content: str,
     ontology_class: NodeType,
-    metadata: Dict[str, str],
+    metadata: dict[str, str],
     indentation_level: int,
 ) -> None:
     package = SovereignNotePackage(
@@ -90,9 +89,7 @@ class LogseqASTParser:
                     trees.append("\n".join(current_tree))
                 current_tree = [line]
             else:
-                if current_tree:
-                    current_tree.append(line)
-                elif line.strip():
+                if current_tree or line.strip():
                     current_tree.append(line)
         if current_tree:
             trees.append("\n".join(current_tree))
@@ -122,7 +119,7 @@ T = TypeVar("T", bound=BaseModel)
 def call_local_llm(
     system_prompt: str, user_content: str, response_model: type[T]
 ) -> T | None:
-    payload: Dict[str, Any] = {
+    payload: dict[str, Any] = {
         "model": "local-model",
         "messages": [
             {"role": "system", "content": system_prompt},
@@ -204,7 +201,7 @@ async def main() -> None:
         if filename.startswith("."):
             continue
         filepath = os.path.join(INBOX_DIR, filename)
-        with open(filepath, "r", encoding="utf-8") as f:
+        with open(filepath, encoding="utf-8") as f:
             global_skeleton = f.read()
         macro_buckets = LogseqASTParser.chunk_into_buckets(
             global_skeleton, max_chars=15000
@@ -247,7 +244,7 @@ async def main() -> None:
                     if not note_filename.endswith(".md"):
                         note_filename += ".md"
                     try:
-                        metadata: Dict[str, str] = {
+                        metadata: dict[str, str] = {
                             "source_filename": filename,
                             "confidence": str(extracted_base.confidence),
                             "extracted_at": datetime.now().isoformat(),

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logseq-matryca-parser"
-version = "1.2.2"
+version = "1.3.0"
 description = "The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -76,6 +76,14 @@ dev = [
     "ruff>=0.15.12",
 ]
 
+[tool.uv]
+constraint-dependencies = [
+    "aiohttp>=3.14.1",
+]
+override-dependencies = [
+    "nltk @ git+https://github.com/nltk/nltk@v3.10.0-rc1",
+]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
@@ -95,3 +103,16 @@ module = [
     "watchdog.*",
 ]
 ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+exclude = ["legacy", "examples", "scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/logseq_matryca_parser/kinetic.py" = ["B008"]
+"tests/**" = ["SIM117"]

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/src/logseq_matryca_parser/__init__.py

@@ -4,8 +4,9 @@ from __future__ import annotations
 
 import sys
 
-__version__ = "1.2.2"
+__version__ = "1.3.0"
 
+from .agent_press import SessionAliasRegistry
 from .agent_writer import LogseqConfigReader, logseq_agent_write
 from .exceptions import BlockReferenceError, LogseqIndentationError, LogseqParserError
 from .forge import (
@@ -16,7 +17,15 @@ from .forge import (
     ObsidianForgeVisitor,
 )
 from .graph import LogseqGraph
-from .logos_core import ASTVisitor, LogseqNode, LogseqPage, LogosNode, SovereignNotePackage
+from .logos_core import ASTVisitor, LogosNode, LogseqNode, LogseqPage, SovereignNotePackage
+from .logos_parser import (
+    LOGSEQ_PATTERNS,
+    LogosParser,
+    PageRegistry,
+    StackMachineParser,
+    clean_node_content,
+    is_system_block,
+)
 from .logseq_markdown import (
     format_logseq_block_property_lines,
     format_logseq_page_properties,
@@ -26,12 +35,19 @@ from .logseq_markdown import (
 from .logseq_paths import (
     decode_page_title_segment,
     derive_page_title_from_source_path,
+    discover_graph_files,
     encode_page_title_segment,
     filename_to_page_title,
     is_excluded_graph_path,
     page_title_to_filename,
     page_title_to_relative_path,
 )
+from .synapse import SynapseAdapter, page_source_node_id
+
+try:
+    from .lens import GraphVisualizer
+except ImportError:  # optional [viz] extra (networkx / pyvis)
+    GraphVisualizer = None  # type: ignore[misc, assignment]
 
 
 def ensure_aot_compatibility() -> None:
@@ -46,6 +62,7 @@ __all__ = [
     "BlockReferenceError",
     "FlatListForgeVisitor",
     "ForgeExporter",
+    "GraphVisualizer",
     "JSONForgeVisitor",
     "LOGSEQ_PATTERNS",
     "LogosNode",
@@ -56,22 +73,26 @@ __all__ = [
     "LogseqNode",
     "LogseqPage",
     "LogseqParserError",
+    "MarkdownForgeVisitor",
+    "ObsidianForgeVisitor",
     "PageRegistry",
+    "SessionAliasRegistry",
     "SovereignNotePackage",
     "StackMachineParser",
+    "SynapseAdapter",
     "clean_node_content",
-    "ensure_aot_compatibility",
     "decode_page_title_segment",
     "derive_page_title_from_source_path",
+    "discover_graph_files",
     "encode_page_title_segment",
+    "ensure_aot_compatibility",
     "filename_to_page_title",
     "format_logseq_block_property_lines",
     "format_logseq_page_properties",
     "is_excluded_graph_path",
     "is_system_block",
     "logseq_agent_write",
-    "MarkdownForgeVisitor",
-    "ObsidianForgeVisitor",
+    "page_source_node_id",
     "page_title_to_filename",
     "page_title_to_relative_path",
     "serialize_logseq_page",

{logseq_matryca_parser-1.2.2 → logseq_matryca_parser-1.3.0}/src/logseq_matryca_parser/forge.py

@@ -179,10 +179,7 @@ def _replace_block_refs_in_text(
 
 def _obsidian_line_source(node: LogseqNode) -> str:
     """Prefer the first line of ``content`` so ``((uuid))`` survives when stripped from ``clean_text``."""
-    if node.content:
-        first = node.content.split("\n", 1)[0]
-    else:
-        first = node.clean_text
+    first = node.content.split("\n", 1)[0] if node.content else node.clean_text
     stripped = LOGSEQ_PATTERNS["inline_uuid_prop"].sub("", first)
     return stripped.replace("\n", " ").strip()