logseq-matryca-parser 1.10.0__tar.gz → 1.11.0__tar.gz

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/.gitattributes

@@ -1 +1,2 @@
 tests/fixtures/compat/** text eol=lf
+tests/fixtures/org/** text eol=lf

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/AGENTS.md

@@ -11,6 +11,14 @@ and safely extend a vault without flattening its structure.
 Markdown files are the source of truth. The in-memory graph, registries,
 backlinks, exports, visualizations, and AI chunks are derived views.
 
+The v1.11.0 release line also contains an experimental read-only Org reader
+behind a private, non-stable module API. It accepts Org text or one selected
+`.org` file and does not load a vault graph. Its diagnostics cover selected
+conditions only; unknown syntax may be retained without a warning. Do not
+present this subset as complete GNU Org or Logseq support. Markdown remains the
+primary supported parser surface; see
+[`docs/internal/LOGSEQ_ORG_PARSER_EXPERIMENTAL_STATUS.md`](docs/internal/LOGSEQ_ORG_PARSER_EXPERIMENTAL_STATUS.md).
+
 ## Capability map
 
 | Layer | Use it for | Primary entry point |

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-10-02
+
+### Added
+
+- **Experimental Logseq Org reader** — add a read-only, source-preserving
+  parser for Org text or one caller-selected `.org` file. It remains a private,
+  non-stable API and does not load a vault graph. Its fixed diagnostics cover
+  selected conditions only; unsupported syntax may be retained without a
+  warning. Retained text or a diagnostic-free result does not mean that Org or
+  Logseq semantics were understood. Review the original source when omitted
+  behavior matters.
+
+### Fixed
+
+- **Source archive hygiene** — exclude selected ignored local maintainer and
+  tool-cache directories from source distributions; runtime behavior is unchanged.
+
+### Security
+
+- **Development-toolchain security** — update the locked `virtualenv` from
+  21.5.1 to 21.14.4, closing four Dependabot advisories in the `pre-commit`
+  development dependency chain. Published runtime dependencies are unchanged.
+
 ## [1.10.0] - 2026-09-27
 
 ### Changed

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/CONTRIBUTING.md

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

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.10.0
+Version: 1.11.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
@@ -194,6 +194,13 @@ 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. |
 
+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
+Logseq semantics. Its diagnostics are selective, not a complete inventory of
+unsupported syntax. See the [API stability contract](docs/reference/API_STABILITY.md)
+and [release highlights](RELEASE_HIGHLIGHTS.md).
+
 The base parser is local-first and has zero telemetry. Optional AI, watcher, and
 visualization dependencies remain lazy. See the [architecture](docs/ARCHITECTURE.md)
 and [API stability reference](docs/reference/API_STABILITY.md) for exact boundaries.
@@ -353,13 +360,16 @@ We welcome issues, pull requests, and constructive feedback.
 
 ## 📦 Release history
 
-Version 1.10.0 release notes are prepared, but the package has not yet been
-published to PyPI. The latest published release remains v1.9.0.
+As of 2026-10-02, version 1.11.0 is prepared but not published; v1.10.0 is the
+latest published and supported release. Preparing these notes does not publish
+a package or change support status.
 
 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.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.
 - **v1.9.0** — Adds the stable in-memory snapshot graph factory, clarifies the Parser-Plumber boundary, and governs the temporary optional-NLTK advisory exception.
 - **v1.8.2** — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and `Path | str` graph loading.
 - **v1.8.1** — Hardened deep-outline parsing, coherent incremental graph mutations, bounded assurance cleanup, and stable provenance for optional NLTK.

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/README.md

@@ -155,6 +155,13 @@ 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. |
 
+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
+Logseq semantics. Its diagnostics are selective, not a complete inventory of
+unsupported syntax. See the [API stability contract](docs/reference/API_STABILITY.md)
+and [release highlights](RELEASE_HIGHLIGHTS.md).
+
 The base parser is local-first and has zero telemetry. Optional AI, watcher, and
 visualization dependencies remain lazy. See the [architecture](docs/ARCHITECTURE.md)
 and [API stability reference](docs/reference/API_STABILITY.md) for exact boundaries.
@@ -314,13 +321,16 @@ We welcome issues, pull requests, and constructive feedback.
 
 ## 📦 Release history
 
-Version 1.10.0 release notes are prepared, but the package has not yet been
-published to PyPI. The latest published release remains v1.9.0.
+As of 2026-10-02, version 1.11.0 is prepared but not published; v1.10.0 is the
+latest published and supported release. Preparing these notes does not publish
+a package or change support status.
 
 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.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.
 - **v1.9.0** — Adds the stable in-memory snapshot graph factory, clarifies the Parser-Plumber boundary, and governs the temporary optional-NLTK advisory exception.
 - **v1.8.2** — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and `Path | str` graph loading.
 - **v1.8.1** — Hardened deep-outline parsing, coherent incremental graph mutations, bounded assurance cleanup, and stable provenance for optional NLTK.

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/RELEASE_HIGHLIGHTS.md

@@ -7,12 +7,32 @@ published artifacts and attestations, see
 
 ## Unreleased
 
-The Parser is separating native LlamaIndex export into a companion package.
-The compatibility method remains, but the proposed companion is not yet
-published; Parser `[ai]` provides LangChain, while `[all]` also includes
-visualization dependencies. Neither extra installs LlamaIndex or NLTK. See
-the [support matrix](docs/reference/CONFORMANCE_SUPPORT_MATRIX.md) for the
-current boundary.
+No unreleased highlights are currently recorded.
+
+## v1.11.0
+
+Status note dated 2026-10-02: this release is prepared but not yet published;
+v1.10.0 remains the latest published package as of that date.
+
+Minor release — adds an experimental, read-only Logseq Org reader while keeping
+the existing Markdown parser and graph workflow unchanged.
+
+| Area | Change |
+| :--- | :--- |
+| **Org input** | Parses Org text or one caller-selected `.org` file without loading a vault graph; the API remains private and non-stable. |
+| **Scope and diagnostics** | Diagnostics cover selected conditions, not every unsupported construct. Preserved source text or no diagnostic does not establish that Org or Logseq semantics were understood; inspect the original source when needed. |
+| **Source archive hygiene** | Excludes selected ignored local maintainer and tool-cache directories from source distributions; runtime behavior is unchanged. |
+
+## v1.10.0
+
+Minor release — clarifies the native LlamaIndex companion boundary and removes
+the Parser's NLTK dependency chain. No intentional breaking changes to the
+existing package API or CLI behavior.
+
+| Area | Change |
+| :--- | :--- |
+| **LlamaIndex boundary** | Keeps `SynapseAdapter.to_llamaindex_nodes()` as a lazy compatibility shim while native node construction moves to a separate companion. |
+| **Dependency security** | Removes `llama-index-core` and NLTK from Parser extras, lock, and package metadata; the `[ai]` extra provides LangChain and `[all]` also adds visualization dependencies. |
 
 ## v1.9.0
 

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/SECURITY.md

@@ -2,15 +2,15 @@
 
 ## Supported Versions
 
-Security fixes are provided **only for the latest released version** on [PyPI](https://pypi.org/project/logseq-matryca-parser/). The latest supported release is v1.9.0.
+Security fixes are provided **only for the latest released version** on [PyPI](https://pypi.org/project/logseq-matryca-parser/). As of 2026-10-02, the latest supported release is v1.10.0.
 
-Version 1.10.0 release preparation does not change this support status; it will
+Version 1.11.0 release preparation does not change this support status; it will
 do so only after publication to PyPI.
 
 | Version | Supported |
 | ------- | --------- |
-| **1.9.0** (latest released) | Yes |
-| 1.8.2 and older | No |
+| **1.10.0** (latest released) | Yes |
+| 1.9.0 and older | No |
 
 We recommend always running the current release and upgrading promptly when a security advisory is published.
 

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/SUPPORT.md

@@ -36,6 +36,12 @@ model-provider support, or compatibility with undocumented private APIs. Optiona
 AI and visualization integrations remain separately documented and may have
 their own dependency or upstream support requirements.
 
+The experimental Org reader in the v1.11.0 release line is an internal,
+non-stable interface, not part of the supported public API. It does not load a
+vault graph or promise full Org or Logseq semantics. Its selected diagnostics do
+not identify every unsupported construct; see the
+[API stability contract](docs/reference/API_STABILITY.md) before relying on it.
+
 Security response expectations are defined in [`SECURITY.md`](SECURITY.md).
 General issue response time depends on maintainer availability; opening an issue
 does not guarantee a feature or a fixed release date.

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/CLEAN_CODE_ARCHITECTURE.md

@@ -8,9 +8,9 @@ audience: contributors
 owner: logseq-matryca-parser
 authority: source_repository
 execution_mode: reviewed
-last_verified: 2026-09-27
-verified: 2026-09-27
-stale_after: 2027-03-26
+last_verified: 2026-10-02
+verified: 2026-10-02
+stale_after: 2027-03-31
 okf_profile: matryca_okf_inspired_quality
 okf_spec_version: null
 supersedes: null
@@ -19,7 +19,7 @@ superseded_by: null
 
 # Clean Code & Clean Architecture — Logseq Matryca Parser
 
-**Version:** documents maintainer contracts refreshed for **v1.10.0** release preparation; v1.10.0 is not yet published (v1 structural backlog complete; parser, graph-coherence, local-assurance, and stable snapshot-graph slices merged)
+**Version:** maintainer contracts refreshed for the **v1.11.0** release cycle; the release candidate includes the experimental Org-reader slice (v1 structural backlog complete; parser, graph-coherence, local-assurance, and stable snapshot-graph slices merged)
 **Audience:** contributors and Cursor agents patching `src/logseq_matryca_parser/`  
 **Companion:** [`ARCHITECTURE.md`](ARCHITECTURE.md) (LOGOS domain contract) · [`BUG_HUNT_REPORT.md`](BUG_HUNT_REPORT.md) (audit evidence) · [`CONTRIBUTING.md`](../CONTRIBUTING.md)
 

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/README.md

@@ -8,9 +8,9 @@ audience: contributors
 owner: logseq-matryca-parser
 authority: source_repository
 execution_mode: reviewed
-last_verified: 2026-08-30
-verified: 2026-08-30
-stale_after: 2027-02-26
+last_verified: 2026-10-02
+verified: 2026-10-02
+stale_after: 2027-03-31
 okf_profile: matryca_okf_inspired_quality
 okf_spec_version: null
 supersedes: null
@@ -55,8 +55,12 @@ entry points.
 | [`REPOSITORY_STELLAR_ROADMAP_2026-08-06.md`](REPOSITORY_STELLAR_ROADMAP_2026-08-06.md) | Maintainers, contributors | Dated evidence-backed audit baseline, confirmed defects, and original issue map; the public roadmap is the current execution view |
 | [`REPOSITORY_GOVERNANCE_AAIF_STUDY_2026-08-19.md`](REPOSITORY_GOVERNANCE_AAIF_STUDY_2026-08-19.md) | Maintainers | GitHub governance, supply-chain, agent interoperability, and AAIF-readiness study |
 | [`LSDOC_REFERENCE_STUDY_AND_EXECUTION_PLAN_2026-08-16.md`](LSDOC_REFERENCE_STUDY_AND_EXECUTION_PLAN_2026-08-16.md) | Maintainers, parser contributors | License-safe comparative study and execution plan for semantic, complexity, and source-location assurance |
+| [`superpowers/specs/2026-09-29-logseq-org-parser-design.md`](superpowers/specs/2026-09-29-logseq-org-parser-design.md) | Maintainers | Approved, review-gated design for a read-only Org parser scoped to Logseq OG file graphs |
+| [`superpowers/plans/2026-09-29-logseq-org-parser.md`](superpowers/plans/2026-09-29-logseq-org-parser.md) | Maintainers | D2 implementation and six-cell hosted qualification; D3 deferred and Markdown parser work prioritized |
+| [`internal/LOGSEQ_ORG_PARSER_EXPERIMENTAL_STATUS.md`](internal/LOGSEQ_ORG_PARSER_EXPERIMENTAL_STATUS.md) | Maintainers | Experimental Org subset, selected diagnostics, explicit non-conformance limits, and deferred scope |
+| [`internal/LLAMAINDEX_COMPANION_MIGRATION_CHECKPOINT_2026-09-27.md`](internal/LLAMAINDEX_COMPANION_MIGRATION_CHECKPOINT_2026-09-27.md) | Maintainers | Historical Parser/companion checkpoint with a dated 2026-10-02 live-status refresh |
 | [`README_READABILITY_REPORT_2026-08-08.md`](README_READABILITY_REPORT_2026-08-08.md) | Maintainers | Measured human and AI README assessment with a phased simplification proposal |
-| [`quality/OPEN_ISSUE_RECONCILIATION_2026-09-24.md`](quality/OPEN_ISSUE_RECONCILIATION_2026-09-24.md) | Maintainers | Current disposition of all 33 live open issues and four open PRs |
+| [`quality/OPEN_ISSUE_RECONCILIATION_2026-09-24.md`](quality/OPEN_ISSUE_RECONCILIATION_2026-09-24.md) | Maintainers | Dated 2026-09-24 issue/PR snapshot; rebind live GitHub state before acting |
 | [`decisions/index.md`](decisions/index.md) | Maintainers | Canonical decision registry, including the external-oracle boundary |
 | [`reference/index.md`](reference/index.md) | Maintainers, integrators | Provenance and Matryca ecosystem relations |
 | [`reference/DIAGNOSTICS.md`](reference/DIAGNOSTICS.md) | Integrators, contributors | Stable diagnostic codes, payload schema, path safety, CLI rendering, and escalation |

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/RELEASE_PROCESS.md

@@ -48,6 +48,8 @@ version; use `vX.Y.Z` for the git tag).
 - [ ] Leave an empty `## [Unreleased]` section at the top
 - [ ] Set `__version__ = "X.Y.Z"` in `src/logseq_matryca_parser/_version.py`; the pinned Hatchling backend derives package metadata from this single source
 - [ ] Update `README.md`, `SECURITY.md`, and contributor-facing current-version references
+- [ ] Reconcile `RELEASE_HIGHLIGHTS.md`, support/API contracts, `AGENTS.md`, `llms.txt`, and maintained documentation indexes with shipped capabilities; keep historical records dated and append current status rather than rewriting past evidence
+- [ ] Audit the exact source distribution for ignored local caches, maintainer state, private paths, and secret-like values; do not rely on a clean checkout assumption alone
 - [ ] Verify every file, command, issue disposition, and shipped capability
       named in the versioned changelog against the exact release commit
 - [ ] Run `make all` (Ruff, Mypy, documentation checks, and Pytest)

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/design-docs/LOGSEQ_ASSET_RESOLUTION_SPEC.md

@@ -27,7 +27,7 @@ In a typical Markdown environment, a relative path like ../assets/image.png woul
 | :---- | :---- | :---- | :---- |
 | Relative Asset | ../assets/file.png | Graph-Root Relative | Standard for dragged-and-dropped assets; resolves to \[graph-root\]/assets/file.png. 5 |
 | Local Asset | assets/file.png | Root-Relative | Often used in older graphs or specific plugins; assumes the root as the base. 4 |
-| Absolute System | file:///C:/Users/Graph/assets/a.png | OS Path | Fragile and non-portable; bypassed by Logseq's internal relative logic during sync. 5 |
+| Absolute System | file:///example-vault/assets/a.png | OS Path | Fragile and non-portable; bypassed by Logseq's internal relative logic during sync. 5 |
 | External URI | https://example.com/a.png | Remote URL | Handled by the browser/Electron layer; not considered a local asset. 7 |
 
 One of the significant points of friction in the current implementation is the inconsistent handling of the double-dot .. notation in file:// links. Research indicates that Logseq sometimes ignores leading .. segments, incorrectly resolving them to logseq/assets/ instead of stepping up to the parent directory of the graph.4 For the LOGOS parser, the primary resolution algorithm must prioritize a search path that begins at the graph root. If an asset reference begins with assets/ or ../assets/, the parser should immediately prepend the graph root path, effectively normalizing the reference.
@@ -233,7 +233,7 @@ JSON
   "annotation\_id": "1698059081568\_0",
   "source\_pdf": {
     "logical\_name": "how\_to\_take\_smart\_notes.pdf",
-    "absolute\_path": "/home/user/graph/assets/how\_to\_take\_smart\_notes.pdf",
+    "absolute\_path": "/example-vault/assets/how\_to\_take\_smart\_notes.pdf",
     "mime\_type": "application/pdf"
   },
   "highlight\_data": {
@@ -305,4 +305,4 @@ This technical specification provides the roadmap for building a high-fidelity b
 24. Markdown vs Orgmode \- Which format should one choose? : r/logseq \- Reddit, accessed on April 25, 2026, [https://www.reddit.com/r/logseq/comments/1by05ql/markdown\_vs\_orgmode\_which\_format\_should\_one\_choose/](https://www.reddit.com/r/logseq/comments/1by05ql/markdown_vs_orgmode_which_format_should_one_choose/)
 25. 0.8.18 · Milestone \#12 · logseq/logseq \- GitHub, accessed on April 25, 2026, [https://github.com/logseq/logseq/milestone/12?closed=1](https://github.com/logseq/logseq/milestone/12?closed=1)
 26. Creating Link Aliases in Logseq \- Preslav Rachev, accessed on April 25, 2026, [https://preslav.me/2022/04/10/create-link-aliases-in-logseq/](https://preslav.me/2022/04/10/create-link-aliases-in-logseq/)
-27. Support subdirs for namespace hierarchy \- Feature Requests \- Logseq forum, accessed on April 25, 2026, [https://discuss.logseq.com/t/support-subdirs-for-namespace-hierarchy/9763](https://discuss.logseq.com/t/support-subdirs-for-namespace-hierarchy/9763)
+27. Support subdirs for namespace hierarchy \- Feature Requests \- Logseq forum, accessed on April 25, 2026, [https://discuss.logseq.com/t/support-subdirs-for-namespace-hierarchy/9763](https://discuss.logseq.com/t/support-subdirs-for-namespace-hierarchy/9763)

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/index.md

@@ -8,9 +8,9 @@ audience: maintainers
 owner: logseq-matryca-parser
 authority: source_repository
 execution_mode: reviewed
-last_verified: 2026-09-27
-verified: 2026-09-27
-stale_after: 2027-03-26
+last_verified: 2026-10-02
+verified: 2026-10-02
+stale_after: 2027-03-31
 okf_profile: matryca_okf_inspired_quality
 okf_spec_version: null
 supersedes: null
@@ -36,6 +36,9 @@ navigation layers only.
 | [AI contribution policy](AI_CONTRIBUTION_POLICY.md) | Human accountability, privacy, disclosure, and review rules for AI-assisted work |
 | [Agent action contract](reference/AGENT_ACTION_CONTRACT.md) | Read/write authority, provenance, prompt-injection boundary, and approval matrix |
 | [Support and compatibility matrix](reference/CONFORMANCE_SUPPORT_MATRIX.md) | Supported runtimes, public API tiers, optional integrations, companion boundary, and explicit limits |
+| [Org reader limits](internal/LOGSEQ_ORG_PARSER_EXPERIMENTAL_STATUS.md) | Experimental private Org subset, selected diagnostics, and explicit non-conformance limits |
+| [Org reader implementation plan](superpowers/plans/2026-09-29-logseq-org-parser.md) | Completed D2 qualification; D3 graph integration deferred and Markdown improvement prioritized |
+| [LlamaIndex companion migration checkpoint](internal/LLAMAINDEX_COMPANION_MIGRATION_CHECKPOINT_2026-09-27.md) | Historical migration evidence with a dated current-state refresh; rebind live PR and release state before action |
 | [Dependency, license, SBOM, and provenance policy](reference/DEPENDENCY_LICENSE_POLICY.md) | Release evidence, override, checksum, and attestation contract |
 | [Daily metrics threat model](security/DAILY_METRICS_THREAT_MODEL.md) | Security boundary for the self-mutating repository traffic archive |
 | [Dependency advisory exceptions](security/DEPENDENCY_ADVISORY_EXCEPTIONS.md) | Exact, time-bounded security audit exceptions and compensating controls |

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/internal/ASSURANCE_TERRA_HANDOFF_2026-08-21.md

@@ -4,7 +4,7 @@ This handoff records a checkpoint; it is not a validation or release receipt.
 
 ## Safe resume point
 
-- Repository: `/Users/marco1/Documents/CODICE con VS CODE/logseq-matryca-parser`
+- Repository: Logseq Matryca Parser (historical handoff; local checkout path omitted)
 - Additional worktree: none; the maintainer prefers in-place execution when a
   clean checkout can preserve every branch remotely.
 - Branch: `feat/graph-mutation-coherence-103`

{logseq_matryca_parser-1.10.0 → logseq_matryca_parser-1.11.0}/docs/internal/LLAMAINDEX_COMPANION_MIGRATION_CHECKPOINT_2026-09-27.md

@@ -3,9 +3,13 @@ type: Document
 ---
 # LlamaIndex companion migration checkpoint — 2026-09-27
 
+> Historical snapshot captured on 2026-09-27. The resume anchors and pending
+> Parser 1.10.0 publication statements below describe that checkpoint only.
+> Use the dated status refresh at the end before resuming.
+
 ## Resume anchors
 
-- Parser: PR #225 has since merged; exact remote `main` is `870a35eb8014c030aaa874e8f1ce550556e0decb` (verified 2026-09-27). Earlier code qualification anchor was `1d11d97e1806b534a74a82585fc1aec54e56a4fa`; candidate-wheel gate source HEAD was `95154fa32f6f13ebb1f9b6accc26ccace8ff2435`, clean at gate time. Version 1.10.0 remains release preparation only and is not yet published to PyPI.
+- Parser: PR #225 had merged by this checkpoint; exact remote `main` was `870a35eb8014c030aaa874e8f1ce550556e0decb` (verified 2026-09-27). Earlier code qualification anchor was `1d11d97e1806b534a74a82585fc1aec54e56a4fa`; candidate-wheel gate source HEAD was `95154fa32f6f13ebb1f9b6accc26ccace8ff2435`, clean at gate time. At this checkpoint, version 1.10.0 remained release preparation and was not yet published to PyPI.
 - Companion: [draft PR #1](https://github.com/MarcoPorcellato/logseq-matryca-parser-llamaindex/pull/1), branch `feat/native-llamaindex-adapter`; tested head `14fd8de399d5abd38c70e52125e81da8dda5c5b2`. Its bootstrap `main` is `47d954a713712b8a433970f9b0f23db070ee09b9`.
 - Both candidate-wheel source checkouts were clean at the gate HEADs above. Preserve any dirty primary checkout and rebind repository and branch state before further work. Local workspace paths are intentionally omitted from this public record.
 
@@ -34,3 +38,29 @@ type: Document
 6. Review the companion draft PR's exact hosted checks and complete its applicable qualification before any merge. Companion publication remains a separate authorization gate.
 
 See the [implementation plan](../superpowers/plans/2026-09-27-llamaindex-companion-separation.md) for task ownership and detailed acceptance criteria.
+
+## Current status refresh — 2026-10-02
+
+This update preserves the checkpoint evidence above and supersedes its current
+release/PR statements. Rebind the exact repository, branch, and hosted checks
+again before acting.
+
+- Parser v1.10.0 is published on PyPI and GitHub. The GitHub release was
+  published 2026-09-28; tag `v1.10.0` resolves to
+  `4966144b5cd3e95ce36d38c8c1a9823a6ecab056`. PyPI reports 1.10.0 as latest
+  on this verification date.
+- Parser PR #225 merged 2026-09-27 at
+  `870a35eb8014c030aaa874e8f1ce550556e0decb`. Org parser PR #229 merged
+  2026-10-01 at `09df7069dca553005123162fd24cd847d1b3456c`. The current Parser
+  `main` observed on 2026-10-02 is `8c07b2e9235852fcbf9aac16bce5ff13bcc82534`.
+- Companion PR #1 remains open and draft at head
+  `e6824c3e50aeac942b01a9aa3f2bbed1663b1230`; its PyPI distribution returned
+  HTTP 404 on this date. Rebind the PR head and checks before any decision.
+- The companion's provisional Parser range remains
+  `>=1.10.0,<1.11.0`; publication of Parser 1.10.0 makes the lower bound
+  registry-available but does not qualify the companion. The upper bound does
+  not admit Parser 1.11.0 and must not be widened without a separate
+  compatibility review.
+- Parser v1.11.0 is under release preparation and has no published tag as of
+  this update. Its experimental Org reader remains private and non-stable; that
+  Parser release does not qualify or publish the separate companion.

logseq_matryca_parser-1.11.0/docs/internal/LOGSEQ_ORG_PARSER_EXPERIMENTAL_STATUS.md

@@ -0,0 +1,245 @@
+---
+type: Document
+title: Experimental Logseq Org parser implementation status
+description: Internal evidence and support boundary for the unreleased, read-only Org subset parser.
+status: draft
+classification: active
+audience: maintainers
+owner: logseq-matryca-parser
+authority: source_repository
+execution_mode: reviewed
+last_verified: 2026-10-02
+verified: 2026-10-02
+stale_after: 2026-10-31
+okf_profile: matryca_okf_inspired_quality
+okf_spec_version: null
+supersedes: null
+superseded_by: null
+---
+
+# Experimental Logseq Org parser implementation status
+
+> Internal and unreleased experimental work. This page is not a stable API,
+> compatibility promise, product support statement, or Logseq Org conformance
+> claim. No package-root export or supported public API is authorized. The
+> informational row in the public support matrix records this boundary; it
+> does not promote the private entrypoints to a supported interface.
+
+## Scope and API boundary
+
+The work implements an explicitly selected, read-only Org file/text parser for
+a bounded Logseq OG-oriented subset. The entrypoints live in the private
+`logseq_matryca_parser._org_parser` module:
+`parse_org_text(text, *, page_title=...)` and
+`parse_org_file(path, *, page_title=...)`. They return a source-preserving
+private IR and Org-local diagnostics. The caller must supply a non-empty page
+title; identity is not derived from the file path, a headline, or `#+TITLE`.
+The file path is not included in the parse result or diagnostics.
+
+The parser does not provide graph loading, whole-vault discovery, page or
+backlink resolution, a writer or round-trip serializer, watcher integration,
+Logseq DB support, or full Org-mode conformance. It is not integrated with
+`LogseqGraph.load_directory()`. It adds no package-root export. All recognized
+or unrecognized executable-looking Org content remains inert: source/query/
+dynamic/macro constructs are not executed or expanded. Links and embeds are
+not resolved, and formulas are not evaluated. The explicit file entrypoint
+reads only the selected source file through the private source boundary.
+
+## Implemented subset
+
+The implementation follows the finite grammar in the
+[approved design](../superpowers/specs/2026-09-29-logseq-org-parser-design.md):
+
+- Source-ordered headings with levels 1–128, literal `TODO`/`DONE`/`WAITING`
+  markers, optional A–Z priority, and final tag spans. These are source facts,
+  not workflow-state semantics.
+- Generic `#+KEY: value` directives; inert source, query, dynamic, and named
+  blocks; and opaque macro directives. Blocks do not nest. Only the exact
+  matching closer closes an active block. Source/query/dynamic openers and
+  macro directives produce bounded warnings; their bodies are never run.
+- `:PROPERTIES:` drawers attach to a heading only when immediately following
+  it, with ordered key/value spans; unowned drawers remain opaque. An unclosed
+  drawer remains opaque through EOF and produces one error at its opener.
+- Unordered `- ` lists with ASCII-space indentation in two-space increments.
+  A candidate without an active parent is a paragraph, not a list item.
+- Date-only `SCHEDULED:` and `DEADLINE:` values in the exact Gregorian
+  `<YYYY-MM-DD Ddd>` form. `CLOSED:` and `CLOCK:` are opaque timestamps; ranges,
+  repeaters, timezone conversion, and time-tracking behavior are not modeled.
+- Paragraph-only `[[target]]` and `[[target][label]]` references. Internal page
+  targets remain unresolved; external targets are preserved; `file:` targets
+  are marked never-resolved. No target is opened or fetched.
+- LF/CRLF line boundaries, one optional initial BOM for recognition, source
+  spans over the original unnormalized text, and ASCII space/tab blank-line
+  rules. Other unsupported syntax remains source text or an opaque element.
+
+This subset does not establish Logseq's graph identity rules, property
+inheritance, configured TODO workflows, block references, embeds, table/media
+semantics, macro expansion, or equivalence to Logseq's complete parser.
+
+## Unsupported syntax and diagnostics
+
+The parser does not produce a complete per-document inventory of unsupported
+Org syntax. Its diagnostics identify selected conditions in the finite
+recognizer only. Unknown syntax may remain a generic directive, paragraph, or
+other source-preserving element without a diagnostic; `OrgOpaque` elements and
+warnings do not enumerate every omitted feature. Therefore, a diagnostic-free
+result is not evidence of full Org or Logseq semantic support, and retained
+source text is not the same as parsed meaning. Review the original source when
+behavior outside this subset matters. Any future public Org entrypoint must
+state this limitation beside its usage guidance.
+
+## Input, resource, and work bounds
+
+Limits are inclusive; crossing a limit returns no document with a fixed
+Org-local error. The file reader accepts one absolute caller-selected `.org`
+path, capped at 32,767 path code points, and at most 8,388,608 source bytes.
+File bytes are size-checked before strict UTF-8 decoding; invalid or truncated
+UTF-8 returns `ORG_INVALID_UTF8`. The caller-supplied title is required and is
+limited to 1,024 UTF-8 bytes. Title validation scans left-to-right and checks
+at most 1,025 code points (4,100 charged title-work units): a surrogate
+encountered before byte overflow returns `ORG_INVALID_UNICODE`; the first
+valid scalar that pushes the byte count over 1,024 returns
+`ORG_PAGE_TITLE_TOO_LARGE` immediately, without inspecting the suffix. Only a
+complete in-limit scan classifies an empty or Unicode-whitespace-only title
+as `ORG_PAGE_TITLE_REQUIRED`. This validation precedes all file I/O. The
+parser allows at most 250,000 logical lines,
+100,000 source occurrences, nesting depth 128, and 256 total diagnostics.
+Source occurrences include top-level elements, one list node per run, every
+list item, property entry, inline link annotation, and heading-tag occurrence.
+The 256th diagnostic slot is reserved for a truncation marker if ordinary
+diagnostics would exceed 255.
+
+The audited abstract scanner budget is
+`W <= 64 * (B + N + T + E + L + 1)`, where `B` is source UTF-8 bytes, `N` and
+`T` are source/title code points, `E` is counted source occurrences, and `L` is
+indexed logical lines. Its phase ceilings are `8B` file read/decode allowance,
+`4N` source scalar/UTF-8 validation, at most `4 * 1,025` title-validation
+work units (and no more than `4T`), `4N+L` line
+indexing, `16N+2L` recognition/scanning, and `48E+4L+16` allocation/fixed
+allowance. This is an abstract charged-work contract, not a CPU-time,
+I/O-latency, or wall-clock guarantee. The text entrypoint does not use the
+`8B` file allowance.
+
+## File-reader boundary and accepted residuals
+
+The design profile is Linux x86-64 on ext-family filesystems, macOS arm64 on
+APFS, and Windows x64 on NTFS, with component-at-a-time no-follow handling,
+same-handle checks, a raw path grammar, fixed path-free diagnostics, and
+fail-closed behavior outside the profile. This is a qualification target, not
+a claim that every release, architecture, filesystem, provider, or mounted
+volume is supported.
+
+POSIX paths must be absolute, have a lower-case `.org` leaf suffix, and
+contain no empty, `.` or `..` component. Windows also requires a lower-case
+`.org` leaf suffix, accepts only drive-rooted backslash paths, rejects
+namespaces, ADS, reserved device names and other invalid components, and caps
+each component at 255 UTF-16 code units (also respecting the selected
+volume's reported maximum component length).
+
+The accepted contract does not promise that rejection has no prior OS/provider
+effects; a selected remote-backed path can trigger provider I/O. It does not
+prove physical locality, immutable contents while another writer changes the
+file, exclusive hard-link provenance, or a hard wall-clock I/O deadline. The
+byte cap bounds bytes consumed, not read duration. These residuals do not
+authorize broader path access: only the caller-selected source is read.
+
+## Verification and open gates
+
+Evidence below describes the local implementation review only. It does not
+imply native platform qualification, stable API status, or a release.
+
+The focused local Org test run before the later filesystem-transition
+regressions reported 199 passed and one platform-specific skip.
+
+The final review identified a gap in per-component transition coverage. Two
+test-only additions now verify each held POSIX component before proceeding and
+define native Windows regular-file, directory, parent-reparse, and leaf-reparse
+checks. The focused POSIX/Windows reader tests pass 53 tests and skip five
+platform-specific checks on this macOS host. These additions do not qualify
+native Windows behavior.
+
+The earlier full-suite skip was the native Linux x86-64 `fstatfs` ABI test,
+which cannot qualify Linux behavior on this macOS arm64 host. Final full-suite
+evidence after the test-only review repairs and evidence-note edits is recorded
+below.
+
+The new `tests/test_org_source_imports.py` regression passed and checks for
+static import cycles among the Org source-reader modules. A refreshed local
+source audit over the current worktree also returned zero import cycles. This
+supersedes the earlier statement that only the base-`HEAD` index had been
+checked. The test is a repository regression gate; the audit result is a
+current local observation, not hosted CI evidence.
+
+An sdist built from a dirty worktree included maintainer-only data. A separate
+clean-source snapshot passed the wheel contract, Twine validation, and
+downstream typing checks. This evidence applies only to those exact sanitized
+artifacts and does not establish that arbitrary dirty-worktree builds are safe.
+
+### Package-source hygiene diagnosis
+
+The unsafe sdist came from building a dirty maintainer worktree, not from the
+tag-triggered release workflow. The repository's ordinary clean-tree check
+does not report ignored files. Hatch documents VCS-based sdist selection and
+explicit include/exclude controls ([build configuration](https://hatch.pypa.io/1.13/config/build/),
+[sdist builder](https://hatch.pypa.io/1.16/plugins/builder/sdist/)).
+
+The current tag workflow runs its pre-flight and artifact build from fresh
+checkouts of the exact tag; the build then creates and verifies one immutable
+bundle before PyPI publication. The local dirty-build finding therefore does
+not demonstrate leakage through that hosted path. At the 2026-10-01 checkpoint,
+no durable source-selection policy had been added, so arbitrary dirty-worktree
+artifacts were not publishable on that evidence. The parser implementation in
+PR #229 did not change packaging configuration or the release workflow.
+
+The initial whole-branch Sol review returned `BLOCKED` for incomplete
+held-component transition coverage and a dirty-worktree sdist that included
+maintainer-local files. Test-only coverage was added, and a separate clean
+source snapshot passed the wheel contract, Twine, and downstream typing checks.
+A later review found that the nine-document privacy sanitizer had also changed
+historical command wrappers and environment semantics. That documentation
+regression is corrected: `rtk`, `UV_NO_SYNC=1`, and command structure are
+preserved; only machine-specific path values are replaced with portable
+temporary paths. Fresh whole-branch Sol review returned `PASS_WITH_NOTES`; at
+that pre-merge point, its remaining note was that native Linux x86-64 and
+Windows x64 qualification still needed CI evidence. That evidence is recorded
+below. Fresh local diff inventory and a bounded privacy scan found
+only intended Org changes and the nine authorized document sanitizations, with
+no machine-local path or identifier matches in those nine documents. Minor
+inertness-test suggestions remain deferred; source review found no executable
+Org constructs.
+
+The final local quality gate passed on Python 3.12.13/macOS arm64 after the
+sanitizer correction: Ruff, Mypy across 98 source files,
+maintained-documentation and vendor-name checks; 1,032 tests passed, five
+platform-specific tests skipped, no warnings, 89.79% coverage, 226.94 seconds.
+Test caches and coverage output were isolated outside the checkout. Skips
+include Linux `fstatfs` ABI and native Windows reader checks; this is not Linux
+or Windows qualification.
+
+A fresh clean-source wheel/sdist gate passed on 2026-10-01 after the latest
+status and plan checkpoint correction: wheel contract, Twine 6.2.0, strict
+downstream typing on the installed wheel, and artifact privacy review all
+passed. The 303-entry sdist contained each of the 16 scoped Markdown documents
+exactly once and excluded the local restart handoff plus cache/build artifacts.
+The scoped scan found no machine-specific user, home, temporary-directory,
+worktree, or cache values; portable `${TMPDIR}` examples in historical plans
+remain intentional. These local gates do not qualify native Linux or Windows
+execution.
+
+**Native qualification completed (2026-10-01):** PR [#229](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/229) was squash-merged at `09df7069dca553005123162fd24cd847d1b3456c`; its tested head was `2d5ef3b30e3d515841539be58a8dce0a34d5b1aa`. All 14 GitHub check runs completed successfully. The native test matrix passed on `ubuntu-24.04`, `macos-15`, and `windows-2025`, each with Python 3.12 and 3.13; Quality, CodeQL, production dependency audit, wheel/source-distribution contract, dependency review, and static analyses also passed. These results qualify only that exact PR head and matrix, not every OS version, filesystem/provider, or full GNU Org/Logseq conformance. The Linux-native `fstatfs` and Windows checks skipped by the local macOS arm64 run remain skipped in that local run; the hosted native results are separate evidence.
+
+The refreshed local source audit and `tests/test_org_source_imports.py` both report zero Org source-reader import cycles. The D1 full-suite receipt predates this parser and is not current evidence. An earlier default-cache limitation in a documentation check was handled with an isolated environment/cache; maintained-docs, vendor-name, and diff checks passed.
+
+**Remaining scope:** this remains an experimental, unreleased, read-only Org subset parser, not a stable API or full Org compatibility claim. D3 graph loading—including mixed `.md`/`.org` selection, page identity/collisions, namespace and journal paths, aliases/backlinks, indexing, and refresh behavior—requires a separate reviewed design before implementation. Watchers, writing/round-trip, and Logseq DB support remain deferred. PR #229 is merged; no release or package publication is implied by its CI qualification.
+
+## Release-preparation update — 2026-10-02
+
+Parser v1.11.0 is prepared but not tagged or published. Separate release
+preparation adds explicit Hatch source-distribution exclusions for these
+selected ignored local directories: `.ccp`, `.ccp-mounts`, `.claude`, `.cursor`,
+`.hypothesis`, `.serena`, and `.superpowers`. This addresses the observed local
+tooling/cache paths; it is a bounded exclusion list, not a general guarantee
+that every arbitrary dirty-worktree artifact is safe to publish. A fresh
+wheel/source build and artifact scan must still pass after any later change.
+This packaging-only adjustment does not expand Org-parser behavior or alter the
+clean-checkout tag-triggered release workflow.