logseq-matryca-parser 1.0.0__tar.gz → 1.1.1__tar.gz

{logseq_matryca_parser-1.0.0 → logseq_matryca_parser-1.1.1}/.cursorignore

@@ -1,10 +1,35 @@
 # .cursorignore
 # (Nota: Cursor ignora già automaticamente tutto ciò che è nel .gitignore)
 
+# =========================
+# Python & Virtual Environments
+# =========================
+.venv/
+venv/
+env/
+__pycache__/
+*.pyc
+
+# =========================
+# Linter & Test Caches
+# =========================
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# =========================
+# Build Artifacts
+# =========================
+dist/
+build/
+*.egg-info/
+
 # =========================
 # Lockfiles (Letali per il Codebase Indexing)
 # =========================
-# I lockfile devono stare su Git, ma l'IA non deve MAI leggerli, 
+# I lockfile devono stare su Git, ma l'IA non deve MAI leggerli,
 # sono solo un muro di versioni incomprensibili.
 poetry.lock
 uv.lock
@@ -33,7 +58,7 @@ tests/fixtures/*.md
 # =========================
 # Assets Vettoriali
 # =========================
-# Le immagini PNG/JPG Cursor le ignora da solo, ma gli SVG sono file di testo! 
+# Le immagini PNG/JPG Cursor le ignora da solo, ma gli SVG sono file di testo!
 # Se l'IA legge un SVG, legge migliaia di coordinate matematiche inutili.
 *.svg
 
@@ -42,4 +67,4 @@ tests/fixtures/*.md
 # =========================
 .vscode/
 .idea/
-.clinerules
+.clinerules

logseq_matryca_parser-1.1.1/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to **logseq-matryca-parser** (The Logos Protocol) are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.1] - 2026-05-28
+
+### Added
+
+- **Graph page aliases** — `LogseqGraph.load_directory` honors `title::`, `alias::` / `aliases::` for `pages` lookup and backlinks; incremental reload re-applies enrichment after watcher edits.
+- **LaTeX math shielding** — `_shield_inline_code` masks `$$...$$` and `$...$` spans so wikilinks/tags inside equations are not extracted.
+- **Datalog query dead zones** — `#+BEGIN_QUERY` … `#+END_QUERY` blocks are ignored for entity extraction (parse-loop state plus shielding).
+- **Numbered list blocks** — `logos_parser.py` recognizes ordered-list markers (`1. `, `12. `, etc.) as outliner bullets alongside `-` and `*`.
+- **Markdown task checkboxes** — `[ ]`, `[-]`, and `[x]`/`[X]` on block text map to `TODO`, `DOING`, and `DONE` before Org-mode prefix fallback.
+
+### Fixed
+
+- **Logseq OG parity (parser)** — `{{embed [[Page]]}}` and similar macros expose nested wikilinks; Unicode tags and markdown boundaries (`**#tag**`, `==#tag==`); comma-separated `tags::` / `alias::` / `aliases::` inject implicit graph tokens; `~~~` fences share code-block immunity with ` ``` ` fences.
+- **Property contiguity** — block `key:: value` lines apply only while contiguous below the bullet; after a soft-break, later `key::` lines stay in `content` / `clean_text` (Logseq-native behavior).
+- **Property bullet lists** — empty `alias::` / `tags::` followed by indented `-` bullets serialize as `list[str]` without orphan AST children.
+- **Case-insensitive property keys** — all property keys normalized to lowercase at parse time; `TITLE::` frontmatter overrides graph page titles like `title::`.
+- **Extended task markers** — `DELEGATED`, `POSTPONED`, `IN-PROGRESS` (longest-prefix matching) alongside existing Org-mode statuses.
+- **Aliased block references** — `[Visible](((uuid)))` clean text retains visible alias only (no surrounding `[` `]`).
+
+## [1.0.0] - 2026-05-28
+
+### Added
+
+- **LOGOS engine** — deterministic Stack-Machine parser (`StackMachineParser`) producing strict `LogseqPage` / `LogseqNode` ASTs from Spatial Markdown.
+- **SYNAPSE adapters** — LangChain and LlamaIndex exporters with parent-child lineage metadata.
+- **FORGE exporters** — JSON, Markdown, Obsidian, and enriched chunk payloads.
+- **LENS visualizer** — interactive topology HTML via NetworkX / PyVis.
+- **KINETIC CLI** — `matryca-parse` Typer entry point for export, visualization, and agent read/write workflows.
+- **Headless CRUD** — append-only agent writer and X-Ray press utilities for sovereign graph mutation.
+- **Logseq-native serialization** — round-trip page and block property layout via `logseq_markdown.py`.
+- **Graph query layer** — `LogseqGraph` with backlinks, effective property inheritance, and optional filesystem watcher.

{logseq_matryca_parser-1.0.0 → logseq_matryca_parser-1.1.1}/CONTRIBUTING.md

@@ -8,6 +8,20 @@ To maintain the architectural integrity of the project, please follow the guidel
 
 ---
 
+## 📚 Documentation
+
+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.1.1**) and **Unreleased** changes (Keep a Changelog)
+- [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) — version bump, tag, and PyPI publish checklist
+
+When you add or change observable parser or graph behavior, update the relevant doc sections and add a bullet under **`## [Unreleased]`** in `CHANGELOG.md` (see [`.cursor/rules/05-auto-changelog.mdc`](.cursor/rules/05-auto-changelog.mdc)).
+
+---
+
 ## 🏛️ Architectural Philosophy
 
 Before writing any code, please understand our core principles:

{logseq_matryca_parser-1.0.0 → logseq_matryca_parser-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.0.0
+Version: 1.1.1
 Summary: The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai.
 Project-URL: Homepage, https://github.com/MarcoPorcellato/logseq-matryca-parser
 Project-URL: Bug Tracker, https://github.com/MarcoPorcellato/logseq-matryca-parser/issues
@@ -47,7 +47,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.0.0 Stable** — heavily tested (156+ tests), full bidirectional Headless CRUD engine, native markdown serialization, and static typing; ready for production Enterprise integration.
+**v1.1.1** — Logseq OG parity release (see [CHANGELOG](CHANGELOG.md)) — **200+ tests**, full bidirectional Headless CRUD engine, native markdown serialization, and static typing; ready for production Enterprise integration.
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -57,7 +57,7 @@ Description-Content-Type: text/markdown
 
 [👉 **TRY THE LIVE INTERACTIVE DEMO**](https://MarcoPorcellato.github.io/logseq-matryca-parser/)
 
-[📘 **READ THE ARCHITECTURE (LLM OS Vision)**](docs/ARCHITECTURE.md)
+[📘 **ARCHITECTURE**](docs/ARCHITECTURE.md) · [AST Primer](docs/logseq_ast_primer.md) · [Changelog](CHANGELOG.md) · [Release process](docs/RELEASE_PROCESS.md)
 
 </div>
 
@@ -100,6 +100,7 @@ It acts as the strict **File System Driver** for your LLM OS. By using a determi
 | **Block references `((uuid))`** | Treated as opaque text or dropped | **Resolved** against `LogseqGraph`; optional **embed expansion** and **Obsidian `[[Page#^anchor]]`** export |
 | **Property inheritance** | Page-level frontmatter at best | **`get_effective_properties`**: page + ancestor outline keys merged top-down (Org-mode style), then exposed on enriched chunks |
 | **Live sync** | Re-read whole tree or poll | **`LogseqGraph.start_watching()`** (optional `watchdog`): **per-file invalidation** — re-parse one page, purge stale UUIDs from registries, refresh backlinks |
+| **Page aliases & titles** | Filename-only or manual link maps | **`title::`**, **`alias::`** / **`aliases::`** re-key `graph.pages` and wire **backlinks** for alias wikilinks |
 
 ---
 
@@ -138,7 +139,37 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
-## ⚡ Recent superpowers (Waves 4–12)
+## ⚡ Recent superpowers (v1.1.1)
+
+### Native parity (parser + graph)
+
+| Area | Capability |
+| :--- | :--- |
+| **Graph index** | `title::` / `TITLE::` overrides the filename-derived page title; `alias::` / `aliases::` inject extra keys into `graph.pages` (comma-separated strings, bullet-list values, or Python lists). |
+| **Backlinks** | `[[Dev]]` resolves against alias keys the same way as canonical titles (`get_backlinks("Dev")`). |
+| **Incremental reload** | `invalidate_and_reload_page` re-applies title/alias enrichment after watcher edits. |
+| **Parser shields** | LaTeX `$…$` / `$$…$$`, `#+BEGIN_QUERY` … `#+END_QUERY`, fenced code (` ``` ` and `~~~`), drawers, and `{{embed [[Page]]}}` macros do not emit false wikilinks/tags. |
+| **Property contiguity** | `key:: value` lines apply only while contiguous under the bullet; after a soft-break, later property syntax stays in block text. |
+| **Property bullet lists** | `alias::` / `tags::` with indented `-` children become `list[str]` properties — no spurious AST child nodes. |
+| **Outliner bullets** | Ordered-list markers (`1. `, `12. `, …) are first-class bullets alongside `-` and `*`. |
+| **Tasks** | GFM checkboxes (`[ ]`, `[-]`, `[x]`) plus Org-mode markers including `DELEGATED`, `POSTPONED`, `IN-PROGRESS`. |
+| **Aliased block refs** | `[Label](((uuid)))` cleans to `Label` in `clean_text` for RAG-friendly prose. |
+
+```python
+from logseq_matryca_parser.graph import LogseqGraph
+
+graph = LogseqGraph.load_directory("/path/to/logseq/graph")
+
+# file_name.md with frontmatter: title:: Custom Title
+page = graph.pages["Custom Title"]
+
+# Development.md with alias:: Dev, Coding — wikilinks to aliases resolve
+assert graph.pages["Dev"] is graph.pages["Development"]
+linker = graph.pages["Linker"].root_nodes[0]
+assert linker in graph.get_backlinks("Dev")
+```
+
+Deep dive: [Architecture §3.6 — LogseqGraph](docs/ARCHITECTURE.md#36-logseqgraph--namespace-scoping-o1-invalidation-live-watch) and [AST primer — page properties](docs/logseq_ast_primer.md#5-page-properties-title-aliases-and-graph-indexing).
 
 ### Obsidian-native export
 Compile an entire Logseq graph into an **Obsidian vault layout**: YAML frontmatter from page properties, list body preserved, Logseq `((uuid))` links rewritten to **`[[Page#^anchor]]`**, and trailing **`^block-id`** on referenced blocks. Namespace titles become nested folders (e.g. `Projects/AI/Demo.md`).
@@ -194,8 +225,9 @@ For graph hygiene, **`LogseqGraph.get_broken_references()`** flags nodes whose `
 
 | Feature | Description |
 | :--- | :--- |
-| **LOGOS Engine** | Deterministic AST parsing. No regex-guessing. Handles `id::`, aliases, and multiline blocks. |
-| **Advanced Task Extraction** | Task **state** (TODO / DOING / …), **priority** markers `[#A]`–`[#C]` promoted to `task_priority`, and **SCHEDULED** / **DEADLINE** Logseq timestamps normalized to **UTC Unix epoch seconds** on `scheduled_at` / `deadline_at` for temporal graph and retrieval pipelines. |
+| **LOGOS Engine** | Deterministic AST parsing. Property contiguity, bullet-list properties, lowercase keys, multiline blocks, extended task markers, GFM checkboxes, numbered bullets, and **shielded** code/math/query regions. |
+| **LogseqGraph** | In-memory vault: `pages` index (with **title/alias enrichment**), backlinks, effective properties, namespace resolution, fluent `GraphQuery`, optional **watchdog** invalidation. |
+| **Advanced Task Extraction** | Task **state** (TODO / DOING / DELEGATED / IN-PROGRESS / …), **priority** markers `[#A]`–`[#C]` promoted to `task_priority`, and **SCHEDULED** / **DEADLINE** Logseq timestamps normalized to **UTC Unix epoch seconds** on `scheduled_at` / `deadline_at` for temporal graph and retrieval pipelines. |
 | **SYNAPSE Adapter** | Native exports for **LangChain** and **LlamaIndex** with automated lineage metadata; **context-enriched** chunks with breadcrumbs, embed expansion, and inherited properties. |
 | **FORGE** | JSON, clean Markdown, and **Obsidian** vault serialization (`ObsidianForgeVisitor`, `ForgeExporter.to_obsidian_markdown`). |
 | **LENS Visualizer** | 60FPS interactive graph rendering (10k+ nodes) with Glassmorphism HUD. |
@@ -248,12 +280,17 @@ matryca-parse export /path/to/logseq/graph output --format obsidian
 
 ### Python API
 ```python
+from logseq_matryca_parser.graph import LogseqGraph
 from logseq_matryca_parser.logos_parser import LogosParser
 from logseq_matryca_parser.synapse import SynapseAdapter
 
-# Parse to AST
+# Parse a single page to AST
 page = LogosParser().parse_page_file("page.md")
 
+# Load the whole vault (pages, backlinks, node registry)
+graph = LogseqGraph.load_directory("/path/to/logseq/graph")
+effective = graph.get_effective_properties(graph.pages["My Page"].root_nodes[0].uuid)
+
 # Export to LangChain with lineage metadata
 docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
 ```

{logseq_matryca_parser-1.0.0 → logseq_matryca_parser-1.1.1}/README.md

@@ -11,7 +11,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.0.0 Stable** — heavily tested (156+ tests), full bidirectional Headless CRUD engine, native markdown serialization, and static typing; ready for production Enterprise integration.
+**v1.1.1** — Logseq OG parity release (see [CHANGELOG](CHANGELOG.md)) — **200+ tests**, full bidirectional Headless CRUD engine, native markdown serialization, and static typing; ready for production Enterprise integration.
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -21,7 +21,7 @@
 
 [👉 **TRY THE LIVE INTERACTIVE DEMO**](https://MarcoPorcellato.github.io/logseq-matryca-parser/)
 
-[📘 **READ THE ARCHITECTURE (LLM OS Vision)**](docs/ARCHITECTURE.md)
+[📘 **ARCHITECTURE**](docs/ARCHITECTURE.md) · [AST Primer](docs/logseq_ast_primer.md) · [Changelog](CHANGELOG.md) · [Release process](docs/RELEASE_PROCESS.md)
 
 </div>
 
@@ -64,6 +64,7 @@ It acts as the strict **File System Driver** for your LLM OS. By using a determi
 | **Block references `((uuid))`** | Treated as opaque text or dropped | **Resolved** against `LogseqGraph`; optional **embed expansion** and **Obsidian `[[Page#^anchor]]`** export |
 | **Property inheritance** | Page-level frontmatter at best | **`get_effective_properties`**: page + ancestor outline keys merged top-down (Org-mode style), then exposed on enriched chunks |
 | **Live sync** | Re-read whole tree or poll | **`LogseqGraph.start_watching()`** (optional `watchdog`): **per-file invalidation** — re-parse one page, purge stale UUIDs from registries, refresh backlinks |
+| **Page aliases & titles** | Filename-only or manual link maps | **`title::`**, **`alias::`** / **`aliases::`** re-key `graph.pages` and wire **backlinks** for alias wikilinks |
 
 ---
 
@@ -102,7 +103,37 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
-## ⚡ Recent superpowers (Waves 4–12)
+## ⚡ Recent superpowers (v1.1.1)
+
+### Native parity (parser + graph)
+
+| Area | Capability |
+| :--- | :--- |
+| **Graph index** | `title::` / `TITLE::` overrides the filename-derived page title; `alias::` / `aliases::` inject extra keys into `graph.pages` (comma-separated strings, bullet-list values, or Python lists). |
+| **Backlinks** | `[[Dev]]` resolves against alias keys the same way as canonical titles (`get_backlinks("Dev")`). |
+| **Incremental reload** | `invalidate_and_reload_page` re-applies title/alias enrichment after watcher edits. |
+| **Parser shields** | LaTeX `$…$` / `$$…$$`, `#+BEGIN_QUERY` … `#+END_QUERY`, fenced code (` ``` ` and `~~~`), drawers, and `{{embed [[Page]]}}` macros do not emit false wikilinks/tags. |
+| **Property contiguity** | `key:: value` lines apply only while contiguous under the bullet; after a soft-break, later property syntax stays in block text. |
+| **Property bullet lists** | `alias::` / `tags::` with indented `-` children become `list[str]` properties — no spurious AST child nodes. |
+| **Outliner bullets** | Ordered-list markers (`1. `, `12. `, …) are first-class bullets alongside `-` and `*`. |
+| **Tasks** | GFM checkboxes (`[ ]`, `[-]`, `[x]`) plus Org-mode markers including `DELEGATED`, `POSTPONED`, `IN-PROGRESS`. |
+| **Aliased block refs** | `[Label](((uuid)))` cleans to `Label` in `clean_text` for RAG-friendly prose. |
+
+```python
+from logseq_matryca_parser.graph import LogseqGraph
+
+graph = LogseqGraph.load_directory("/path/to/logseq/graph")
+
+# file_name.md with frontmatter: title:: Custom Title
+page = graph.pages["Custom Title"]
+
+# Development.md with alias:: Dev, Coding — wikilinks to aliases resolve
+assert graph.pages["Dev"] is graph.pages["Development"]
+linker = graph.pages["Linker"].root_nodes[0]
+assert linker in graph.get_backlinks("Dev")
+```
+
+Deep dive: [Architecture §3.6 — LogseqGraph](docs/ARCHITECTURE.md#36-logseqgraph--namespace-scoping-o1-invalidation-live-watch) and [AST primer — page properties](docs/logseq_ast_primer.md#5-page-properties-title-aliases-and-graph-indexing).
 
 ### Obsidian-native export
 Compile an entire Logseq graph into an **Obsidian vault layout**: YAML frontmatter from page properties, list body preserved, Logseq `((uuid))` links rewritten to **`[[Page#^anchor]]`**, and trailing **`^block-id`** on referenced blocks. Namespace titles become nested folders (e.g. `Projects/AI/Demo.md`).
@@ -158,8 +189,9 @@ For graph hygiene, **`LogseqGraph.get_broken_references()`** flags nodes whose `
 
 | Feature | Description |
 | :--- | :--- |
-| **LOGOS Engine** | Deterministic AST parsing. No regex-guessing. Handles `id::`, aliases, and multiline blocks. |
-| **Advanced Task Extraction** | Task **state** (TODO / DOING / …), **priority** markers `[#A]`–`[#C]` promoted to `task_priority`, and **SCHEDULED** / **DEADLINE** Logseq timestamps normalized to **UTC Unix epoch seconds** on `scheduled_at` / `deadline_at` for temporal graph and retrieval pipelines. |
+| **LOGOS Engine** | Deterministic AST parsing. Property contiguity, bullet-list properties, lowercase keys, multiline blocks, extended task markers, GFM checkboxes, numbered bullets, and **shielded** code/math/query regions. |
+| **LogseqGraph** | In-memory vault: `pages` index (with **title/alias enrichment**), backlinks, effective properties, namespace resolution, fluent `GraphQuery`, optional **watchdog** invalidation. |
+| **Advanced Task Extraction** | Task **state** (TODO / DOING / DELEGATED / IN-PROGRESS / …), **priority** markers `[#A]`–`[#C]` promoted to `task_priority`, and **SCHEDULED** / **DEADLINE** Logseq timestamps normalized to **UTC Unix epoch seconds** on `scheduled_at` / `deadline_at` for temporal graph and retrieval pipelines. |
 | **SYNAPSE Adapter** | Native exports for **LangChain** and **LlamaIndex** with automated lineage metadata; **context-enriched** chunks with breadcrumbs, embed expansion, and inherited properties. |
 | **FORGE** | JSON, clean Markdown, and **Obsidian** vault serialization (`ObsidianForgeVisitor`, `ForgeExporter.to_obsidian_markdown`). |
 | **LENS Visualizer** | 60FPS interactive graph rendering (10k+ nodes) with Glassmorphism HUD. |
@@ -212,12 +244,17 @@ matryca-parse export /path/to/logseq/graph output --format obsidian
 
 ### Python API
 ```python
+from logseq_matryca_parser.graph import LogseqGraph
 from logseq_matryca_parser.logos_parser import LogosParser
 from logseq_matryca_parser.synapse import SynapseAdapter
 
-# Parse to AST
+# Parse a single page to AST
 page = LogosParser().parse_page_file("page.md")
 
+# Load the whole vault (pages, backlinks, node registry)
+graph = LogseqGraph.load_directory("/path/to/logseq/graph")
+effective = graph.get_effective_properties(graph.pages["My Page"].root_nodes[0].uuid)
+
 # Export to LangChain with lineage metadata
 docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
 ```

{logseq_matryca_parser-1.0.0 → logseq_matryca_parser-1.1.1}/docs/ARCHITECTURE.md

@@ -187,9 +187,17 @@ Auxiliary **FORGE** serialization (JSON / flat Markdown / Obsidian) appears as a
   - **Push** the freshly built `LogseqNode` onto the stack and register its UUID with `PageRegistry` for deterministic identity and future block-reference linkage.
   This yields **finite-state, linear-time** traversal with explicit ascend/descend behavior — not regex-driven whole-document guessing.
 
-- **Spatial indentation rules.** In Logseq, **indentation defines the AST**, not list decoration. Heading blocks and bullets both participate as first-class structural lines. Levels are **normalized post-pass** to tree depth (`_normalize_indent_levels`) so persisted `indent_level` reflects hierarchical depth independent of authoring quirks after stack repair.
+- **Spatial indentation rules.** In Logseq, **indentation defines the AST**, not list decoration. Heading blocks and bullets both participate as first-class structural lines. The bullet detector accepts **unordered markers** (`-`, `*`) and **ordered-list markers** (`1. `, `12. `, …) via a shared `BULLET_PATTERN`, so numbered outlines participate in the stack machine like standard bullets. Levels are **normalized post-pass** to tree depth (`_normalize_indent_levels`) so persisted `indent_level` reflects hierarchical depth independent of authoring quirks after stack repair.
 
-- **Block properties & `id::`.** Subsequent lines matching `key:: value` attach to **`current_node`** (or accumulate into **frontmatter-derived page properties** when no node exists yet). Parsed properties live in **`LogseqNode.properties`**. Native **`id::`** values are preserved in **`source_uuid`** (and in **`properties["id"]`** when applicable) so **`((uuid))`** references match Logseq; the parser’s stable **`uuid`** field remains the synthetic identity used for AST wiring and adapters.
+- **GFM task checkboxes (before Org-mode tasks).** On the first line of a block, GitHub-flavored checkboxes are recognized and mapped to **`task_status`** before Org-mode prefix fallback: `[ ]` → **`TODO`**, `[-]` → **`DOING`**, `[x]` / `[X]` → **`DONE`**. The checkbox token is stripped from **`clean_text`** so embeddings stay prose-only.
+
+- **Org-mode task prefixes (extended).** After checkbox handling, **`_extract_task_status`** matches longest-first Org prefixes (`TODO`, `DOING`, `DELEGATED`, `IN-PROGRESS`, …) at the start of the first line and promotes the remainder to **`clean_text`**.
+
+- **Protected regions (entity extraction dead zones).** Wikilink, tag, and block-reference harvesters run on **`_shield_inline_code`**-masked text so literals inside **fenced code** (backtick and tilde fences), **inline code**, **LaTeX** (`$…$` and `$$…$$`), **`#+BEGIN_QUERY` … `#+END_QUERY`** blocks (parse-loop state plus shielding), and **Org drawers** do not produce false graph tokens. **`{{embed [[Page]]}}`** and similar macros are **not** fully opaque: nested wikilinks inside embed bodies are harvested for graph indexing.
+
+- **Block properties & `id::`.** Subsequent lines matching `key:: value` attach to **`current_node`** only while **`properties_allowed`** remains true (contiguous property window immediately under the bullet). A **soft-break** continuation disables further property extraction; later `key::` lines merge into **`content`** as plain text. Keys are normalized with **`_normalize_property_key`** (lowercase) for Datomic parity. An empty value (`alias::` with no inline text) opens a **pending bullet-list** accumulator: indented `-` / `*` lines deeper than the property line become **`list[str]`** values without creating child **`LogseqNode`** entries. Page frontmatter uses the same key normalization (`TITLE::` ≡ `title::`). Parsed properties live in **`LogseqNode.properties`**. Native **`id::`** values are preserved in **`source_uuid`** (and in **`properties["id"]`** when applicable) so **`((uuid))`** references match Logseq; the parser’s stable **`uuid`** field remains the synthetic identity used for AST wiring and adapters.
+
+- **Aliased block references in `clean_text`.** Markdown links of the form **`[Visible](((uuid)))`** are reduced to **`Visible`** in **`clean_text`** (brackets stripped) while UUIDs still populate **`block_refs`** for graph resolution.
 
 #### Sovereign UUID architecture and zero-corruption guarantee
 
@@ -276,6 +284,24 @@ Both paths keep **existing topology intact** relative to their contract: append-
 
 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.
 
+#### 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).
+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.
+
+**Incremental parity:** **`invalidate_and_reload_page`** drops **all** `pages` keys tied to the file’s `source_path` (not only the first alias hit), merges the freshly parsed page, re-runs **`_enrich_pages_index`**, then re-registers nodes and appends backlinks for the enriched instance. **`_page_title_for_source_path`** returns the canonical **`page.title`**, not an arbitrary alias key.
+
+```python
+graph = LogseqGraph.load_directory("/vault")
+dev = graph.pages["Dev"]              # alias key
+assert dev is graph.pages["Development"]
+assert linker in graph.get_backlinks("Dev")
+```
+
 #### Namespace shadowing (`resolve_relative_page_link`)
 
 Relative page resolution follows **Logseq-style longest-prefix wins**: for a current page title split on **`/`** (namespace segments), the resolver tries candidates **`prefix + "/" + link_target`** for prefixes from **full namespace down to empty**, and returns the **first title that exists** in `pages`. Only if no contextual page exists does it fall back to a **global** title match. Thus a contextual page **`Progetti/AI/Sviluppo`** **shadows** a global **`Sviluppo`** when resolving from **`Progetti/AI/Matryca`** — matching the **nested-namespace shadowing** semantics described in the scoping roadmap.
@@ -287,9 +313,9 @@ Full-directory loads are expensive for always-on agents. **`invalidate_and_reloa
 1. Ignore paths outside tracked **`pages/*.md`** and **`journals/*.md`**.
 2. Re-parse the file with **`StackMachineParser.parse_page_file`**, producing a fresh `LogseqPage`.
 3. If the path previously mapped to a page, collect **all synthetic UUIDs** from the old tree and call **`_purge_stale_page_uuids`**: remove each UUID from **`_node_registry`**, scrub those UUIDs from every **`_backlink_registry`** source list, and delete backlink keys that become empty.
-4. Replace the **`pages`** dict entry (title may change if the file moved), then **`_register_page_nodes`** and **`_append_page_backlinks`** for the new AST.
+4. Remove every **`pages`** key whose value shares the file’s **`source_path`**, insert the freshly parsed page under its filename title, run **`_enrich_pages_index`** (title + aliases), then **`_register_page_nodes`** and **`_append_page_backlinks`** for the enriched page.
 
-This keeps **global indexes consistent** without rebuilding the entire graph.
+This keeps **global indexes consistent** without rebuilding the entire graph — including alias keys and custom titles declared in frontmatter.
 
 #### Live filesystem watcher (`start_watching`)
 

logseq_matryca_parser-1.1.1/docs/RELEASE_PROCESS.md

@@ -0,0 +1,67 @@
+# Release process
+
+**Logseq Matryca Parser** (The Logos Protocol · Marco Porcellato · [Matryca.ai](https://matryca.ai)) uses a **curated** [`CHANGELOG.md`](../CHANGELOG.md) (Keep a Changelog). PyPI publishing is triggered when you push a `v*` git tag.
+
+---
+
+## During development
+
+Add user-facing bullets under **`## [Unreleased]`** (`Added` / `Changed` / `Fixed` / `Removed` / `Security`). One line per notable change. See [`.cursor/rules/05-auto-changelog.mdc`](../.cursor/rules/05-auto-changelog.mdc).
+
+---
+
+## Release day (local)
+
+Replace `X.Y.Z` with the semver you are shipping (no `v` prefix in `pyproject.toml`; use `vX.Y.Z` for the git tag).
+
+### 1. Prepare (Cursor or manual)
+
+- [ ] Move everything from `[Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md`
+- [ ] Leave an empty `## [Unreleased]` section at the top
+- [ ] Set `version = "X.Y.Z"` in `pyproject.toml`
+- [ ] Run `make all` (ruff, mypy, pytest)
+
+**Cursor shortcut:** ask the agent to *“prepare release vX.Y.Z”* (see [`.cursor/rules/04-release-preparation.mdc`](../.cursor/rules/04-release-preparation.mdc)).
+
+### 2. Verify release notes (optional but recommended)
+
+```bash
+python scripts/extract_changelog.py vX.Y.Z | less
+```
+
+You should see exactly the section that will appear on GitHub if you attach release notes manually.
+
+### 3. Commit, tag, push
+
+```bash
+git add CHANGELOG.md pyproject.toml
+git commit -m "chore: release X.Y.Z"
+git tag vX.Y.Z
+git push origin main
+git push origin vX.Y.Z
+```
+
+### 4. CI does the rest
+
+On tag push, [`.github/workflows/pypi_publish.yml`](../.github/workflows/pypi_publish.yml):
+
+1. Builds sdist and wheel with `python -m build`
+2. Publishes to PyPI (trusted publishing)
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| PyPI version already exists | Bump patch version; never re-use a published version. |
+| Notes look wrong | Re-run locally: `python scripts/extract_changelog.py vX.Y.Z` and compare to `CHANGELOG.md`. |
+| CI fails on tests | Run `make all` locally before tagging. |
+
+---
+
+## Related
+
+- [`CHANGELOG.md`](../CHANGELOG.md)
+- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — quality gates before tag
+- [`scripts/extract_changelog.py`](../scripts/extract_changelog.py)

logseq_matryca_parser-1.1.1/docs/logseq_ast_primer.md

@@ -0,0 +1,152 @@
+# 🧠 Logseq AST Primer: Understanding Spatial Markdown and the Logos Protocol
+
+To contribute to or understand the **Logos Protocol**, you must first understand the idiosyncratic nature of Logseq's data structure. 
+
+Logseq does not use standard Markdown; it uses an **Outliner-based Spatial Markdown**. 
+Standard NLP text splitters and RAG chunkers destroy Logseq data because they parse text linearly. Logseq must be parsed **topologically**.
+
+Here is the domain logic that the Logos Stack-Machine is built to handle.
+
+---
+
+## 1. The Outliner Paradigm (Spatial Indentation)
+
+In standard Markdown, lists are just formatting. In Logseq, **indentation dictates the Abstract Syntax Tree (AST)**. The physical space defines the semantic parent-child relationship.
+
+**Example:**
+
+```markdown
+- Strategy Meeting
+  - Discussed Q3 goals
+    - Marketing budget needs approval
+  - Fired the PR agency
+```
+
+### The AST Translation
+
+- **"Strategy Meeting" (Level 0)** is the Parent.
+- **"Discussed Q3 goals" (Level 1)** is a Child. 
+
+If you delete the parent, this child loses its context. Standard chunkers will split these lines into different vector embeddings, destroying the semantic link. The Logos engine preserves this topology via exact `parent_id` and `path` lineage.
+
+---
+
+## 2. Block Properties (The Metadata Layer)
+
+Logseq allows injecting metadata directly into blocks. These are not standard Markdown frontmatter, but inline key-value pairs that must immediately follow the block's first line.
+
+**Example:**
+
+```markdown
+- Advanced RAG Architecture #[[AI]]
+  id:: 6628ec8c-5544-486a-8d77-62860c239851
+  collapsed:: true
+  custom_state:: verified
+  - First principle of data extraction...
+```
+
+### Parsing Rules for Logos
+
+1. Properties (like `id::`) belong to the block above them and must appear **contiguously** immediately after the bullet line (or after other property lines in the same window).
+2. If a **soft-break** plain-text line appears in the block body, the property window **closes**: later `key:: value` lines are **plain text**, not metadata.
+3. Property keys are stored **lowercase** (`Title::` → `title`) to match Logseq’s case-insensitive Datomic attributes.
+4. They must be stripped from the raw text content to avoid polluting the AI's context window (`clean_node_content` uses case-insensitive matching).
+5. The `id::` property is sacred: it overrides any deterministic UUID generation because it is the native anchor for Logseq's internal block-references `((uuid))`.
+
+**Bullet-list property values** (Logseq-native):
+
+```markdown
+- Root block
+  tags::
+    - Alpha
+    - Beta
+```
+
+When `key::` has no inline value, indented bullet children are absorbed into **`properties["tags"] == ["Alpha", "Beta"]`** — they do **not** become outline child nodes.
+
+---
+
+## 3. Soft Breaks vs. Hard Breaks (Multiline Blocks)
+
+A single block in Logseq can contain multiple lines of text without creating a new node. This is represented by `Shift+Enter` (soft breaks).
+
+**Example:**
+
+```markdown
+- This is the first line of the block.
+  This is the second line of the SAME block.
+  - This is a new child block.
+```
+
+### Parsing Rules for Logos
+
+If a line does not start with a bullet (`-` or `*`), and is not a property (`key:: value`), it is treated as a multiline continuation of the `current_node`.
+
+**Ordered lists:** Lines matching `1. `, `12. `, etc. are treated as structural bullets with the same indentation rules as `-` and `*`.
+
+**GFM checkboxes:** On the first line of a block, `[ ]`, `[-]`, and `[x]` / `[X]` map to `task_status` values `TODO`, `DOING`, and `DONE` respectively (checked before Org-mode prefixes).
+
+**Org-mode task markers:** Prefixes such as `TODO`, `DOING`, `DELEGATED`, `POSTPONED`, and `IN-PROGRESS` (longest match first) set `task_status` and are removed from `clean_text`.
+
+**Aliased block references:** `[My Label](((block-uuid)))` resolves the UUID for `block_refs` but `clean_text` exposes only `My Label` (no square brackets).
+
+---
+
+## 4. Page Properties (Frontmatter) and Graph Indexing
+
+Unlike block properties, **page properties** live at the **top of the file** as raw `key:: value` lines (no leading `- `), followed by a blank line before the first outline bullet.
+
+**Example:**
+
+```markdown
+title:: Custom Title
+alias:: Dev, Coding
+tags:: parser, logseq
+
+- First root block
+```
+
+### Parsing rules
+
+1. Keys and values are stored in **`LogseqPage.properties`** with **lowercase keys**; the parser does **not** automatically change **`LogseqPage.title`** (that remains filename-derived until graph load).
+2. **`alias::`** and **`aliases::`** accept comma-separated strings, **bullet-list** values (`alias::` followed by indented `-` lines), or Python `list` values after parse. Serialization strips `[[wikilink]]` and `#tag` adornments from each token.
+
+### `LogseqGraph` enrichment
+
+When you call **`LogseqGraph.load_directory`**, a post-parse pass:
+
+- Applies **`title::`** → updates **`page.title`** and re-keys **`graph.pages`**
+- Injects **alias keys** → `graph.pages["Dev"]` points to the same object as `graph.pages["Development"]`
+- Builds **backlinks** so `[[Dev]]` resolves like a canonical page link
+
+See [Architecture §3.6](ARCHITECTURE.md#36-logseqgraph--namespace-scoping-o1-invalidation-live-watch) for the full pipeline.
+
+---
+
+## 5. Protected Regions (Dead Zones)
+
+Logseq markdown often contains syntax that **looks** like links or tags but must not become graph entities:
+
+| Region | Why it is shielded |
+| :--- | :--- |
+| Fenced / inline code | Literals such as `[[not-a-page]]` inside samples |
+| LaTeX `$…$` and `$$…$$` | Equations may contain bracket-heavy notation |
+| `#+BEGIN_QUERY` … `#+END_QUERY` | Datalog snippets reference `[[pages]]` symbolically |
+| Org drawers (`:LOGBOOK:`, etc.) | System metadata, not prose |
+| `{{embed [[Page]]}}` macros | Nested wikilinks inside embed bodies **are** extracted for the graph |
+
+The LOGOS engine masks these spans before wikilink/tag/block-ref extraction (see `_shield_inline_code` in `logos_parser.py`). This keeps vector pipelines and backlink registries aligned with **human navigation intent**, not accidental token matches inside non-prose regions.
+
+---
+
+## 6. The Matryca Moat: Why Standard RAG Fails
+
+If you feed Logseq Markdown into `RecursiveCharacterTextSplitter` (LangChain) or similar naive chunkers:
+
+- It splits blocks mid-sentence based on character count.
+- It completely loses the parent-child indentation context.
+- It ingests system properties (e.g., `collapsed:: true`) as semantic text, confusing the LLM.
+
+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), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (**v1.1.1** OG parity).

{logseq_matryca_parser-1.0.0 → logseq_matryca_parser-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logseq-matryca-parser"
-version = "1.0.0"
+version = "1.1.1"
 description = "The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai."
 readme = "README.md"
 requires-python = ">=3.12"