logseq-matryca-parser 1.11.1__tar.gz → 1.11.2__tar.gz

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/AGENTS.md

@@ -61,7 +61,10 @@ filesystem scope, repository scope, network authority, or release decision.
 
 - Read, parse, scan, export, and dry-run operations may proceed only within the
   documented path and vault-containment rules.
-- Writes are opt-in, confined, and require explicit caller or human authority.
+- Bounded Markdown writes are opt-in and require explicit caller or human authority.
+- An X-Ray read also writes an alias-state file; use it only with trusted vaults
+  until that state-write boundary is corrected. It is not covered by the
+  Markdown writer's containment or atomic-replacement guarantees.
 - Repository changes require a reviewable diff and the documented validation
   gate; releases and external publication require an explicit maintainer gate.
 - Record source path, source revision when available, action, applied/proposed

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.11.2] - 2026-10-26
+
+### Fixed
+
+- **Graph ownership enumeration** — resolve distinct published pages and node
+  source paths once per attached-node read instead of rescanning every page
+  for every block. Preserve aliases, collision filtering, node order and
+  coordinated graph snapshots without retaining a cross-operation cache.
+
+### Added
+
+- **Focused refresh-depth matrix** — exercise soft-break, block-property,
+  fenced-code, query and list-property refresh at depths 1, 2, 3, 4, 8 and 32.
+  Extend the existing round-trip families by 20 combinations without changing
+  production code, identity policy or limits; this is not exhaustive coverage.
+
+### Documentation
+
+- Consolidate the [current assurance delivery](docs/quality/COMPOSITE_MARKDOWN_ASSURANCE_2026-10-03.md#current-delivery-and-release-status),
+  [#104 acceptance package](docs/quality/PARSER_ASSURANCE_ACCEPTANCE_2026-10-18.md),
+  architecture residuals and dated contributor catalog. Record approval of
+  #234's permanent regressions without duplicating a formal corpus fixture;
+  preserve release history and separate qualification and issue-closure gates.
+- Add Obsidian to the README PKM comparison and link one source-backed
+  [comparison study](docs/reference/PKM_OBSIDIAN_COMPARISON.md). Distinguish
+  applications from the parser library, native features from community plugins,
+  and compatible output from lossless cross-app support; replace absolute Git,
+  sovereignty and ordinal AI-readiness claims with concrete capabilities.
+
+### Security
+
+- **Development-toolchain updates** — refresh locked `virtualenv` and `filelock`
+  versions in the `pre-commit` development dependency chain (#266). These
+  packages are not part of the base or optional-extra dependency closures.
+- **Locked optional extras** — refresh `packaging` and `certifi` in the locked
+  `ai`/`all` extras closure (#266, #259). The lock supports project audits and
+  release evidence; it does not constrain versions installed by downstream users.
+- **Reading-skill dependency setup** — the bundled reading-skill helper no
+  longer installs Parser from the repository's unpinned default branch when it
+  is missing. It stops and prints manual PyPI installation guidance instead.
+  Earlier source distributions and copied repository skills retain the old
+  behavior; update any copied skill separately.
+
+### Known issues
+
+- **Snapshot graph paths** — some checks and graph reads resolve logical paths
+  against host filesystem metadata. Symlinks can affect ordering or results;
+  see the [API stability contract](docs/reference/API_STABILITY.md).
+- **X-Ray read state** — `matryca-parse agent-read` writes
+  `.matryca_xray_state.json` under the selected graph path. Until the state-write
+  boundary is corrected, use X-Ray only with trusted vaults. The state write is
+  not covered by the Markdown writer's guarantees.
+
 ## [1.11.1] - 2026-10-20
 
 ### Fixed

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.11.1
+Version: 1.11.2
 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
@@ -112,10 +112,17 @@ evidence; they are not included in the current results.
 
 ## 🌐 The Vision: Virtual Centralization vs. Binary Lock-in
 
-The PKM (Personal Knowledge Management) world is currently forcing users to make a painful choice between **Data Longevity** and **AI Power**.
-
-* **Vanilla Logseq / Obsidian** is a "Forest" of decentralized Markdown files. It guarantees the Lindy effect (plain-text lasts forever) and perfect Git versioning, but standard AI chunkers treat it like a blender, destroying the outliner hierarchy.
-* **Tana** is a centralized "Tree". It offers incredible semantic power, but traps your brain in a proprietary cloud database.
+PKM (Personal Knowledge Management) tools differ in where knowledge lives,
+how it is structured, and how other tools can use it. Local files and rich
+structure are not mutually exclusive.
+
+* **Logseq OG file graphs and Obsidian** keep Markdown notes locally but use
+  different block, property and reference conventions. Obsidian also provides
+  a note-link graph, structured properties, Search and Bases; it is not simply
+  a folder without structure.
+* **Tana Outliner** provides linked nodes, fields and supertags in a hosted
+  workspace, with documented Markdown and JSON exports. Export availability
+  and fidelity should be evaluated separately from the working storage model.
 * **The new Logseq DB (SQLite)** uses a local database and provides official
   export paths. Its primary working state is not line-diffable Markdown,
   however, and the semantic fidelity of exported Markdown remains a separate
@@ -142,13 +149,23 @@ does not claim that the separate NLTK advisory is fixed for other consumers.
 
 ## ⚖️ The PKM Landscape
 
-| Feature | Vanilla Markdown | **Matryca Parser** | Logseq DB (SQLite) | Tana |
-| :--- | :--- | :--- | :--- | :--- |
-| **Data Format** | Plain-text (.md) | **Plain-text (.md)** | Local SQLite database with official exports | Proprietary Cloud |
-| **Version Control** | Perfect (Git) | **Perfect (Git)** | Database backup/export; no native line-by-line graph diff | None |
-| **Data Structure** | Decentralized Forest | **Virtually Centralized Graph** | Relational Database | Centralized Tree |
-| **AI Readiness** | Low (Linear Chunks) | **High (Topological AST)** | DB-native; external semantic mapping remains tool-specific | High (Proprietary) |
-| **Sovereignty** | 100% Local | **100% Local (Sovereign AI)** | Local database plus official export paths | Cloud-Only |
+This compares workflows, not product rankings: Markdown is a format;
+Obsidian, Logseq DB and Tana are applications; **Matryca Parser is a Python
+library for Logseq Markdown**, not a replacement editor or sync service.
+
+| Dimension | Vanilla Markdown | Obsidian | **Matryca Parser** | Logseq DB | Tana Outliner |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Working data** | Plain-text `.md` files | Local Markdown vault; optional cloud services | **Logseq Markdown source; derived in-memory AST/graph** | DB graph; local SQLite on desktop | Hosted workspace; documented exports |
+| **Structure and links** | Headings, lists and link conventions | Note-link graph; headings/lists; optional `^block-id` anchors | **Typed block hierarchy, UUIDs, parent/left/path relations** | Linked nodes, properties and tags | Outline and node references |
+| **Metadata and queries** | Depend on chosen tools | YAML properties; native Search and Bases | **Page/block properties, reference resolution, graph queries** | Typed properties and DB queries | Fields, supertags and search nodes |
+| **Automation** | External scripts/tools | TypeScript plugins; CLI requires app; Headless services beta | **Python API and CLI without a note-taking app** | Official CLI and scripting | Product-specific commands and integrations |
+| **History and control** | Git/backup configured separately | Local recovery; external Git; optional Sync history | Local source files; no built-in Git/sync or model-locality guarantee | Database backups and export snapshots | Hosted state and export snapshots |
+| **Portability limits** | Syntax/rendering varies by tool | Extensions, Bases and Canvas need compatible tooling | Obsidian-compatible output; no lossless cross-app round trip promised | SQLite/EDN; Markdown export omits data | Markdown/JSON; Markdown ZIP excludes media |
+
+[Full Obsidian comparison and official sources](docs/reference/PKM_OBSIDIAN_COMPARISON.md)
+explain block identity, native versus community features, current CLI/Headless
+scope and export limits. Obsidian-compatible export does **not** establish a
+native Obsidian-vault input contract.
 
 ---
 
@@ -210,6 +227,10 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 | **Export and integrate — SYNAPSE, FORGE, LENS** | Lineage-aware LangChain exports and context-enriched chunks; LlamaIndex nodes through a separate companion; JSON and Markdown serialization, Obsidian vault generation, and interactive graph visualization. |
 | **Automate safely — KINETIC and agent tools** | CLI parse, scan, export, and visualization; token-efficient X-Ray reads; append-only logging; bounded AST writes; vault containment, dry-run patches, and atomic replacement. |
 
+`agent-read` also writes `.matryca_xray_state.json` under the selected graph
+path. Until its state-write boundary is corrected, use X-Ray only with trusted
+vaults; this state write is not covered by the Markdown writer's guarantees.
+
 The v1.11.0 release line also contains an **experimental, read-only Org
 reader** behind a private, non-stable API. It reads Org text or one selected
 `.org` file; it does not load a vault graph or claim complete GNU Org or
@@ -297,7 +318,7 @@ 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.
+# Build in-memory indexes from captured Markdown; some reads resolve host paths.
 from logseq_matryca_parser import SnapshotPage
 
 snapshot_graph = LogseqGraph.from_snapshot_pages(
@@ -362,13 +383,14 @@ We welcome issues, pull requests, and constructive feedback.
 
 | Resource | Link |
 | :--- | :--- |
-| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) |
+| **Good first issues** | [Recommended starter pack](docs/GOOD_FIRST_ISSUES.md#recommended-starter-pack) — dated Wave 5/6 selection and preserved earlier IDs; recheck GitHub before claiming |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, PR workflow |
 | **Cookbook** | [docs/COOKBOOK.md](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher) |
 | **Documentation index** | [docs/README.md](docs/README.md) — active vs historical docs |
 | **Documentation system** | [docs/DOCUMENTATION_SYSTEM.md](docs/DOCUMENTATION_SYSTEM.md) — authority, lifecycle, metadata, and federation |
 | **Roadmap** | [docs/ROADMAP_2026-2027.md](docs/ROADMAP_2026-2027.md) — milestones, dependencies, and evidence gates |
 | **Markdown compatibility evidence** | [Official Logseq corpus report](docs/quality/OFFICIAL_LOGSEQ_MARKDOWN_COMPATIBILITY_2026-10-10.md) — all 313 selected official documents passed raw-content and tree checks; semantic coverage and limits are explained |
+| **Generated assurance and acceptance** | [Current delivery](docs/quality/COMPOSITE_MARKDOWN_ASSURANCE_2026-10-03.md#current-delivery-and-release-status) and [#104 acceptance package](docs/quality/PARSER_ASSURANCE_ACCEPTANCE_2026-10-18.md) — bounded checks, selected depth coverage and explicit acceptance gates |
 | **Support** | [SUPPORT.md](SUPPORT.md) — safe issue routing, support scope, and response boundaries |
 | **Governance** | [GOVERNANCE.md](GOVERNANCE.md) — decisions, maintainer path, and conflict handling |
 | **Agent safety** | [docs/reference/AGENT_ACTION_CONTRACT.md](docs/reference/AGENT_ACTION_CONTRACT.md) — authority, approvals, provenance, and prompt-injection boundary |
@@ -377,18 +399,21 @@ We welcome issues, pull requests, and constructive feedback.
 
 ## 📦 Release history
 
-Current source version: **v1.11.1**. The [PyPI project page](https://pypi.org/project/logseq-matryca-parser/) and
+Current source version: **v1.11.2**. The [PyPI project page](https://pypi.org/project/logseq-matryca-parser/) and
 [GitHub Releases](https://github.com/MarcoPorcellato/logseq-matryca-parser/releases) list available distributions.
 Security support follows the [latest-release policy](SECURITY.md).
 
-The v1.11.1 source includes fenced-code parsing fixes for outline items, eligible
-multiline scalar-metadata round trips, and bounded composite Markdown assurance.
-See the [changelog](CHANGELOG.md) for scope and limits.
+The v1.11.2 source removes repeated page scans from attached-node graph reads
+while preserving aliases, collision filtering and node order. It also adds a
+focused refresh-depth test matrix and consolidates assurance documentation.
+This does not establish end-to-end Plumber dashboard performance or cancellation.
+See the [changelog](CHANGELOG.md) for scope, limits and known issues.
 
 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.11.2** — Bounds graph ownership-resolution work per read, extends focused refresh-depth tests, and consolidates assurance and PKM comparison documentation.
 - **v1.11.1** — Fixes fenced-code parsing in outline items, preserves eligible multiline scalar-metadata round trips, and adds bounded composite Markdown assurance.
 - **v1.11.0** — Adds an experimental, read-only Logseq Org reader with source retention and explicit support limits.
 - **v1.10.0** — Clarifies the LlamaIndex companion boundary and removes the Parser's NLTK dependency chain.

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/README.md

@@ -73,10 +73,17 @@ evidence; they are not included in the current results.
 
 ## 🌐 The Vision: Virtual Centralization vs. Binary Lock-in
 
-The PKM (Personal Knowledge Management) world is currently forcing users to make a painful choice between **Data Longevity** and **AI Power**.
-
-* **Vanilla Logseq / Obsidian** is a "Forest" of decentralized Markdown files. It guarantees the Lindy effect (plain-text lasts forever) and perfect Git versioning, but standard AI chunkers treat it like a blender, destroying the outliner hierarchy.
-* **Tana** is a centralized "Tree". It offers incredible semantic power, but traps your brain in a proprietary cloud database.
+PKM (Personal Knowledge Management) tools differ in where knowledge lives,
+how it is structured, and how other tools can use it. Local files and rich
+structure are not mutually exclusive.
+
+* **Logseq OG file graphs and Obsidian** keep Markdown notes locally but use
+  different block, property and reference conventions. Obsidian also provides
+  a note-link graph, structured properties, Search and Bases; it is not simply
+  a folder without structure.
+* **Tana Outliner** provides linked nodes, fields and supertags in a hosted
+  workspace, with documented Markdown and JSON exports. Export availability
+  and fidelity should be evaluated separately from the working storage model.
 * **The new Logseq DB (SQLite)** uses a local database and provides official
   export paths. Its primary working state is not line-diffable Markdown,
   however, and the semantic fidelity of exported Markdown remains a separate
@@ -103,13 +110,23 @@ does not claim that the separate NLTK advisory is fixed for other consumers.
 
 ## ⚖️ The PKM Landscape
 
-| Feature | Vanilla Markdown | **Matryca Parser** | Logseq DB (SQLite) | Tana |
-| :--- | :--- | :--- | :--- | :--- |
-| **Data Format** | Plain-text (.md) | **Plain-text (.md)** | Local SQLite database with official exports | Proprietary Cloud |
-| **Version Control** | Perfect (Git) | **Perfect (Git)** | Database backup/export; no native line-by-line graph diff | None |
-| **Data Structure** | Decentralized Forest | **Virtually Centralized Graph** | Relational Database | Centralized Tree |
-| **AI Readiness** | Low (Linear Chunks) | **High (Topological AST)** | DB-native; external semantic mapping remains tool-specific | High (Proprietary) |
-| **Sovereignty** | 100% Local | **100% Local (Sovereign AI)** | Local database plus official export paths | Cloud-Only |
+This compares workflows, not product rankings: Markdown is a format;
+Obsidian, Logseq DB and Tana are applications; **Matryca Parser is a Python
+library for Logseq Markdown**, not a replacement editor or sync service.
+
+| Dimension | Vanilla Markdown | Obsidian | **Matryca Parser** | Logseq DB | Tana Outliner |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Working data** | Plain-text `.md` files | Local Markdown vault; optional cloud services | **Logseq Markdown source; derived in-memory AST/graph** | DB graph; local SQLite on desktop | Hosted workspace; documented exports |
+| **Structure and links** | Headings, lists and link conventions | Note-link graph; headings/lists; optional `^block-id` anchors | **Typed block hierarchy, UUIDs, parent/left/path relations** | Linked nodes, properties and tags | Outline and node references |
+| **Metadata and queries** | Depend on chosen tools | YAML properties; native Search and Bases | **Page/block properties, reference resolution, graph queries** | Typed properties and DB queries | Fields, supertags and search nodes |
+| **Automation** | External scripts/tools | TypeScript plugins; CLI requires app; Headless services beta | **Python API and CLI without a note-taking app** | Official CLI and scripting | Product-specific commands and integrations |
+| **History and control** | Git/backup configured separately | Local recovery; external Git; optional Sync history | Local source files; no built-in Git/sync or model-locality guarantee | Database backups and export snapshots | Hosted state and export snapshots |
+| **Portability limits** | Syntax/rendering varies by tool | Extensions, Bases and Canvas need compatible tooling | Obsidian-compatible output; no lossless cross-app round trip promised | SQLite/EDN; Markdown export omits data | Markdown/JSON; Markdown ZIP excludes media |
+
+[Full Obsidian comparison and official sources](docs/reference/PKM_OBSIDIAN_COMPARISON.md)
+explain block identity, native versus community features, current CLI/Headless
+scope and export limits. Obsidian-compatible export does **not** establish a
+native Obsidian-vault input contract.
 
 ---
 
@@ -171,6 +188,10 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 | **Export and integrate — SYNAPSE, FORGE, LENS** | Lineage-aware LangChain exports and context-enriched chunks; LlamaIndex nodes through a separate companion; JSON and Markdown serialization, Obsidian vault generation, and interactive graph visualization. |
 | **Automate safely — KINETIC and agent tools** | CLI parse, scan, export, and visualization; token-efficient X-Ray reads; append-only logging; bounded AST writes; vault containment, dry-run patches, and atomic replacement. |
 
+`agent-read` also writes `.matryca_xray_state.json` under the selected graph
+path. Until its state-write boundary is corrected, use X-Ray only with trusted
+vaults; this state write is not covered by the Markdown writer's guarantees.
+
 The v1.11.0 release line also contains an **experimental, read-only Org
 reader** behind a private, non-stable API. It reads Org text or one selected
 `.org` file; it does not load a vault graph or claim complete GNU Org or
@@ -258,7 +279,7 @@ 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.
+# Build in-memory indexes from captured Markdown; some reads resolve host paths.
 from logseq_matryca_parser import SnapshotPage
 
 snapshot_graph = LogseqGraph.from_snapshot_pages(
@@ -323,13 +344,14 @@ We welcome issues, pull requests, and constructive feedback.
 
 | Resource | Link |
 | :--- | :--- |
-| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) |
+| **Good first issues** | [Recommended starter pack](docs/GOOD_FIRST_ISSUES.md#recommended-starter-pack) — dated Wave 5/6 selection and preserved earlier IDs; recheck GitHub before claiming |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, PR workflow |
 | **Cookbook** | [docs/COOKBOOK.md](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher) |
 | **Documentation index** | [docs/README.md](docs/README.md) — active vs historical docs |
 | **Documentation system** | [docs/DOCUMENTATION_SYSTEM.md](docs/DOCUMENTATION_SYSTEM.md) — authority, lifecycle, metadata, and federation |
 | **Roadmap** | [docs/ROADMAP_2026-2027.md](docs/ROADMAP_2026-2027.md) — milestones, dependencies, and evidence gates |
 | **Markdown compatibility evidence** | [Official Logseq corpus report](docs/quality/OFFICIAL_LOGSEQ_MARKDOWN_COMPATIBILITY_2026-10-10.md) — all 313 selected official documents passed raw-content and tree checks; semantic coverage and limits are explained |
+| **Generated assurance and acceptance** | [Current delivery](docs/quality/COMPOSITE_MARKDOWN_ASSURANCE_2026-10-03.md#current-delivery-and-release-status) and [#104 acceptance package](docs/quality/PARSER_ASSURANCE_ACCEPTANCE_2026-10-18.md) — bounded checks, selected depth coverage and explicit acceptance gates |
 | **Support** | [SUPPORT.md](SUPPORT.md) — safe issue routing, support scope, and response boundaries |
 | **Governance** | [GOVERNANCE.md](GOVERNANCE.md) — decisions, maintainer path, and conflict handling |
 | **Agent safety** | [docs/reference/AGENT_ACTION_CONTRACT.md](docs/reference/AGENT_ACTION_CONTRACT.md) — authority, approvals, provenance, and prompt-injection boundary |
@@ -338,18 +360,21 @@ We welcome issues, pull requests, and constructive feedback.
 
 ## 📦 Release history
 
-Current source version: **v1.11.1**. The [PyPI project page](https://pypi.org/project/logseq-matryca-parser/) and
+Current source version: **v1.11.2**. The [PyPI project page](https://pypi.org/project/logseq-matryca-parser/) and
 [GitHub Releases](https://github.com/MarcoPorcellato/logseq-matryca-parser/releases) list available distributions.
 Security support follows the [latest-release policy](SECURITY.md).
 
-The v1.11.1 source includes fenced-code parsing fixes for outline items, eligible
-multiline scalar-metadata round trips, and bounded composite Markdown assurance.
-See the [changelog](CHANGELOG.md) for scope and limits.
+The v1.11.2 source removes repeated page scans from attached-node graph reads
+while preserving aliases, collision filtering and node order. It also adds a
+focused refresh-depth test matrix and consolidates assurance documentation.
+This does not establish end-to-end Plumber dashboard performance or cancellation.
+See the [changelog](CHANGELOG.md) for scope, limits and known issues.
 
 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.11.2** — Bounds graph ownership-resolution work per read, extends focused refresh-depth tests, and consolidates assurance and PKM comparison documentation.
 - **v1.11.1** — Fixes fenced-code parsing in outline items, preserves eligible multiline scalar-metadata round trips, and adds bounded composite Markdown assurance.
 - **v1.11.0** — Adds an experimental, read-only Logseq Org reader with source retention and explicit support limits.
 - **v1.10.0** — Clarifies the LlamaIndex companion boundary and removes the Parser's NLTK dependency chain.

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/RELEASE_HIGHLIGHTS.md

@@ -7,8 +7,25 @@ published artifacts and attestations, see
 
 ## Unreleased
 
-No changes are currently listed. See the [changelog](CHANGELOG.md) for the
-current source record.
+## v1.11.2
+
+This patch removes repeated page scans from attached-node graph reads
+and includes the focused assurance and documentation work already merged after
+v1.11.1. Existing public APIs and declared install requirements are unchanged;
+locked development-tool and optional-extra dependency versions were refreshed.
+
+| Area | Change |
+| :--- | :--- |
+| **Graph ownership reads** | Resolves each distinct published page object and each distinct nonempty node source spelling once per read, preserving aliases, collision filtering, node order and coordinated snapshots without a cross-operation cache. |
+| **Focused refresh-depth tests** | Completes the selected five-family/six-depth matrix at depths 1, 2, 3, 4, 8 and 32, adding 20 round-trip combinations without changing parser behavior, identity policy or limits; this complements, not replaces, bounded generated assurance. |
+| **Assurance documentation** | Consolidates the [current delivery record](docs/quality/COMPOSITE_MARKDOWN_ASSURANCE_2026-10-03.md#current-delivery-and-release-status) and [#104 acceptance package](docs/quality/PARSER_ASSURANCE_ACCEPTANCE_2026-10-18.md), preserving dated evidence and separate issue-closure and publication gates. |
+| **PKM comparison** | Adds Obsidian and a [source-backed comparison study](docs/reference/PKM_OBSIDIAN_COMPARISON.md), distinguishing applications, native features, community plugins and compatible export from lossless cross-app support. |
+
+The ownership correction does not qualify whole-request dashboard latency,
+reference-fallback performance, cancellation or downstream Plumber integration.
+The snapshot-path and X-Ray state-write limitations remain; the reading-skill
+helper now stops instead of installing an unpinned dependency. See the
+[changelog](CHANGELOG.md) for scope, dependency notes and known issues.
 
 ## v1.11.1
 

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/claude-skill-logseq-read/SKILL.md

@@ -73,11 +73,12 @@ The script returns structured markdown containing:
 
 ---
 
-## Automatic setup
+## Dependency setup
 
-The script installs `logseq-matryca-parser` automatically if missing.
-If installation fails, install manually with:
+The script does not install dependencies. If the Parser is missing, it prints
+manual installation guidance and exits without reading the vault. Install a
+published release in the same Python environment before running the skill:
 
 ```bash
-uv pip install logseq-matryca-parser
+python -m pip install "logseq-matryca-parser>=1.11.2,<2"
 ```

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/claude-skill-logseq-read/scripts/parse_logseq.py

@@ -15,7 +15,6 @@ Usage:
 import argparse
 import os
 import re
-import subprocess
 import sys
 from datetime import date
 from pathlib import Path
@@ -30,13 +29,15 @@ TASK_ICONS = {"TODO": "☐", "DOING": "🔄", "DONE": "✓", "LATER": "⏳"}
 def ensure_installed():
     try:
         from logseq_matryca_parser import LogosParser  # noqa: F401
-    except ImportError:
-        print("[setup] Installing logseq-matryca-parser...", file=sys.stderr)
-        subprocess.run(
-            [sys.executable, "-m", "pip", "install",
-             "git+https://github.com/MarcoPorcellato/logseq-matryca-parser.git"],
-            check=True, capture_output=True,
+    except ModuleNotFoundError as exc:
+        if exc.name != "logseq_matryca_parser":
+            raise
+        print(
+            'logseq-matryca-parser is not installed. Install it yourself from PyPI: '
+            'python -m pip install "logseq-matryca-parser>=1.11.2,<2"',
+            file=sys.stderr,
         )
+        raise SystemExit(2) from exc
 
 
 def format_node(node, depth=0) -> list[str]:

{logseq_matryca_parser-1.11.1 → logseq_matryca_parser-1.11.2}/docs/CLEAN_CODE_ARCHITECTURE.md

@@ -8,8 +8,8 @@ audience: contributors
 owner: logseq-matryca-parser
 authority: source_repository
 execution_mode: reviewed
-last_verified: 2026-10-04
-verified: 2026-10-04
+last_verified: 2026-10-21
+verified: 2026-10-21
 stale_after: 2027-03-31
 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:** maintainer contracts refreshed for **v1.11.0**, published on 2026-10-02; the release includes the experimental Org-reader slice (v1 structural backlog complete; parser, graph-coherence, local-assurance, and stable snapshot-graph slices merged)
+**Release baseline:** **v1.11.1**, published on 2026-10-20, includes the fenced-code correction, scoped scalar-metadata serializer fix and bounded assurance source. The experimental Org reader remains the private subset introduced in v1.11.0. The selected depth-matrix completion and documentation consolidation are a later local candidate; see the [current assurance record](quality/COMPOSITE_MARKDOWN_ASSURANCE_2026-10-03.md#current-delivery-and-release-status).
 **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,6 +27,15 @@ 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.
 
+**Residual parser work:** line classification and lexical-state extraction are
+delivered. [#108](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/108)
+owns the remaining private reducer and semantic-enrichment slices, after accepted
+[#104](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/104)
+semantic evidence and
+[#111](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/111)
+decision benchmarks. The [#104 acceptance package](quality/PARSER_ASSURANCE_ACCEPTANCE_2026-10-18.md)
+prepares that decision; it does not authorize a refactor or close an issue.
+
 **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
@@ -117,7 +126,7 @@ flowchart TB
 | Pattern | Why it exists | Tracking |
 |---------|---------------|----------|
 | Flat module layout (no `domain/` package) | Library shipped as one PyPI package; low ceremony for contributors | This doc — incremental slices only |
-| `kinetic.py` ~230 lines | Typer app factory + `export` orchestration | **Shipped** — handlers in `kinetic_export.py`, subcommands in `kinetic_commands.py` |
+| Thin KINETIC orchestration | Typer app factory + `export` orchestration | **Shipped** — handlers in `kinetic_export.py`, subcommands in `kinetic_commands.py` |
 | Monolithic SYNAPSE embed `while` loop | Deterministic expansion with cycle guards | **Shipped** — `synapse_embed.py` strategy ([#70](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/70)) |
 | `LogseqGraph.pages` dict with alias keys | Logseq `alias::` / `title::` parity | Point-in-time compatibility mapping; consumers must not mutate it and must use `iter_canonical_pages()` — DEBT-001 **shipped** |
 
@@ -127,7 +136,7 @@ Audit backlog: [`quality/CLEAN_ARCH_BACKLOG.md`](quality/CLEAN_ARCH_BACKLOG.md).
 
 ## Module maps (fat modules)
 
-### `logos_parser.py` (~1,440 lines) — LOGOS stack machine
+### `logos_parser.py` — LOGOS stack machine
 
 | Area | Responsibility |
 |------|----------------|
@@ -145,7 +154,7 @@ uv run pytest tests/test_logos_parser.py -q
 make check
 ```
 
-### `graph.py` (~920 lines) — in-memory graph RAM image
+### `graph.py` — in-memory graph RAM image
 
 | Area | Responsibility |
 |------|----------------|
@@ -174,16 +183,16 @@ 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.
+then reuses the normal graph index builders. The factory does not discover
+source files. Some checks and graph reads resolve logical paths and the root
+label against host filesystem metadata; symlinks can therefore affect ordering
+or results. 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.
 
-### `kinetic.py` (~230 lines) — KINETIC app factory
+### `kinetic.py` — KINETIC app factory
 
 | Area | Responsibility | Module |
 |------|----------------|--------|