okf-parser 0.43.0__tar.gz → 0.45.2__tar.gz

{okf_parser-0.43.0 → okf_parser-0.45.2}/Cargo.lock

@@ -115,9 +115,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "cc"
-version = "1.4.2"
+version = "1.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d262e149917187838d5b42777c8253bcb64500067342904e7d429499a6f277e"
+checksum = "509591b7bcd67f4ef775afad7662703b4935daaa6ec0e5605cfb1090b32a2b6d"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -250,9 +250,9 @@ dependencies = [
 
 [[package]]
 name = "either"
-version = "1.17.0"
+version = "1.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
 
 [[package]]
 name = "encoding_rs"
@@ -265,9 +265,9 @@ dependencies = [
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.10"
+version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "26b73573e6edcd2af0cdf47bd6cb58f0b3839491263c314eaad1ccf24430e1de"
+checksum = "d45db016d36b838f563236e9193d0ee6ce38f3f68b6c94e914b4929c96bbb890"
 
 [[package]]
 name = "foldhash"
@@ -447,7 +447,7 @@ dependencies = [
 
 [[package]]
 name = "okf-core"
-version = "0.43.0"
+version = "0.45.2"
 dependencies = [
  "clap",
  "okf-engine",
@@ -457,7 +457,7 @@ dependencies = [
 
 [[package]]
 name = "okf-engine"
-version = "0.39.1"
+version = "0.45.2"
 dependencies = [
  "chrono",
  "ignore",

{okf_parser-0.43.0 → okf_parser-0.45.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okf-parser
-Version: 0.43.0
+Version: 0.45.2
 Requires-Dist: cyclopts>=4.22,<5
 Requires-Dist: duckdb>=1.4,<2
 Requires-Dist: fastmcp>=3.4,<4
@@ -231,7 +231,7 @@ Add the repository as a CI check:
 ```yaml
 steps:
   - uses: actions/checkout@v7
-  - uses: franklinbaldo/okf-parser@v0.43.0
+  - uses: franklinbaldo/okf-parser@v0.45.2
     with:
       path: knowledge
 ```

{okf_parser-0.43.0 → okf_parser-0.45.2}/README.md

@@ -209,7 +209,7 @@ Add the repository as a CI check:
 ```yaml
 steps:
   - uses: actions/checkout@v7
-  - uses: franklinbaldo/okf-parser@v0.43.0
+  - uses: franklinbaldo/okf-parser@v0.45.2
     with:
       path: knowledge
 ```

{okf_parser-0.43.0 → okf_parser-0.45.2}/benchmarks/README.md

@@ -14,7 +14,7 @@ The default matrix uses 100, 1,000 and 5,000 concepts, five measured rounds and
 one unmeasured warm-up round:
 
 ```bash
-uv run python benchmarks/python_parser.py
+uv run benchmarks/python_parser.py
 npm --prefix typescript run build
 node benchmarks/typescript-parser.mjs
 ```
@@ -22,7 +22,7 @@ node benchmarks/typescript-parser.mjs
 Use the same parameters in both runtimes when changing the corpus:
 
 ```bash
-uv run python benchmarks/python_parser.py \
+uv run benchmarks/python_parser.py \
   --sizes 100,1000 --body-paragraphs 8 --rounds 7 \
   --read-concurrencies 1,4,8,16,32,64
 

{okf_parser-0.43.0 → okf_parser-0.45.2}/benchmarks/python_parser.py

@@ -1,3 +1,14 @@
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "okf-parser",
+# ]
+#
+# [tool.uv.sources]
+# okf-parser = { path = "..", editable = true }
+# ///
 """Reproducible parsing benchmarks for the Python runtime."""
 
 from __future__ import annotations

{okf_parser-0.43.0 → okf_parser-0.45.2}/benchmarks/rust_facts.py

@@ -1,3 +1,14 @@
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "okf-parser",
+# ]
+#
+# [tool.uv.sources]
+# okf-parser = { path = "..", editable = true }
+# ///
 """Compare native Python Markdown facts with the experimental Rust batch core."""
 
 from __future__ import annotations

okf_parser-0.45.2/changelog/0.43.1.md

@@ -0,0 +1,10 @@
+---
+type: Release
+title: okf-parser 0.43.1
+---
+
+# okf-parser 0.43.1
+
+- Fix public-registry preflight so the native npm companion is treated as an npm artifact rather than a PyPI file.
+- Verify `okf-parser-native-linux-x64` version and integrity alongside the main TypeScript package and DuckDB adapter.
+- Include the native npm package in resumable publication planning and in the release completeness decision.

okf_parser-0.45.2/changelog/0.44.0.md

@@ -0,0 +1,10 @@
+---
+type: Release
+title: okf-parser 0.44.0
+---
+
+# okf-parser 0.44.0
+
+- Expose parser-owned concept records for application-facing lookup by concept id or in-bundle Markdown path.
+- Expose validated structured frontmatter from `ConceptRecord`.
+- Add generic frontmatter resource-relation resolution with optional target-type filtering, so consumers do not reparse Markdown or implement bundle containment themselves.

okf_parser-0.45.2/changelog/0.45.0.md

@@ -0,0 +1,10 @@
+---
+type: Release
+title: okf-parser 0.45.0
+---
+
+# okf-parser 0.45.0
+
+- Add an opaque import `preview_token` that binds a reviewed tabular source, import options, candidate paths and current destination states.
+- Let import writes accept `expected_preview_token` and fail before any filesystem mutation when the source or a relevant destination changed after preview.
+- Carry the parser-owned token through the Python service, CLI and MCP write surface so consumers such as Astronauta can remain preview-first without reimplementing import state.

okf_parser-0.45.2/changelog/0.45.1.md

@@ -0,0 +1,9 @@
+---
+type: Release
+title: okf-parser 0.45.1
+---
+
+# okf-parser 0.45.1
+
+- Make `verify-source` enforce Rust crate identity together with the workspace version: `rust-core`, `okf-engine`, and the internal `rust-core -> okf-engine` dependency must all match.
+- Add causal regression tests for drifted crate and dependency versions, closing the gap where the documented release contract allowed Rust metadata to lag behind for multiple releases.

okf_parser-0.45.2/changelog/0.45.2.md

@@ -0,0 +1,11 @@
+---
+type: Release
+title: okf-parser 0.45.2
+---
+
+# okf-parser 0.45.2
+
+- Restore the executable bits on the six repository scripts that carry a `#!/usr/bin/env -S uv run --script` shebang (`scripts/release_contract.py`, `scripts/registry_state.py`, `scripts/native_from_wheel.py`, `scripts/check_no_duckdb_link.py`, `benchmarks/python_parser.py`, `benchmarks/rust_facts.py`). The PEP 723 migration in 0.45.1's follow-up commit committed them as `100644`, so Ruff reported `EXE001` and the whole quality gate stopped before running. Consumers of the source distribution now get scripts that are runnable as declared.
+- Ship the PEP 723 inline dependency headers themselves in the source distribution: the release and benchmark scripts declare `requires-python` and their dependencies inline, so they run standalone with `uv run` without the repository's own environment.
+
+No change to the public Python API, the CLI surface, or the wire protocol; the wheel payload is identical to 0.45.1.

{okf_parser-0.43.0 → okf_parser-0.45.2}/native-npm-linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okf-parser-native-linux-x64",
-  "version": "0.43.0",
+  "version": "0.45.2",
   "description": "Linux x64 native okf-core engine for okf-parser",
   "license": "MIT",
   "os": ["linux"],

{okf_parser-0.43.0 → okf_parser-0.45.2}/okf-engine/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "okf-engine"
-version = "0.39.1"
+version = "0.45.2"
 edition = "2024"
 license = "MIT"
 description = "DuckDB-independent OKF semantic ingestion engine"

{okf_parser-0.43.0 → okf_parser-0.45.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "okf-parser"
-version = "0.43.0"
+version = "0.45.2"
 description = "Relational inspection and validation for Open Knowledge Format bundles"
 readme = "README.md"
 requires-python = ">=3.12"

{okf_parser-0.43.0 → okf_parser-0.45.2}/rust-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "okf-core"
-version = "0.43.0"
+version = "0.45.2"
 edition = "2024"
 license = "MIT"
 description = "Native OKF CLI and compatibility adapters"
@@ -11,6 +11,6 @@ path = "src/main.rs"
 
 [dependencies]
 clap = { version = "4", features = ["derive"] }
-okf-engine = { path = "../okf-engine", version = "0.39.1" }
+okf-engine = { path = "../okf-engine", version = "0.45.2" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{okf_parser-0.43.0 → okf_parser-0.45.2}/scripts/check_no_duckdb_link.py

@@ -1,3 +1,10 @@
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# ]
+# ///
 """Prove a built wheel's executable does not link against a DuckDB library.
 
 The Python distribution depends on `duckdb` and runs its DuckDB export

{okf_parser-0.43.0 → okf_parser-0.45.2}/scripts/native_from_wheel.py

@@ -1,3 +1,10 @@
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# ]
+# ///
 """Reuse the exact Linux x86_64 executable from a Python wheel in npm-native."""
 
 from __future__ import annotations

{okf_parser-0.43.0 → okf_parser-0.45.2}/scripts/registry_state.py

@@ -1,3 +1,10 @@
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# ]
+# ///
 """Inspect public package registries without performing any mutation."""
 
 from __future__ import annotations
@@ -114,9 +121,13 @@ def _string(mapping: dict[str, object], key: str, label: str) -> str:
 # Not a fixed enum here on purpose: registry_state.py stays decoupled from
 # release_contract.py's exact wheel-kind names (one per supported platform,
 # e.g. "python-wheel-linux-x86_64") so adding/removing a target platform
-# never requires touching this file. Any kind other than the two npm
-# packages is treated as a PyPI artifact for okf-parser.
-_NPM_KINDS: Final = {"npm-parser", "npm-duckdb"}
+# never requires touching this file. Any kind other than npm package kinds is
+# treated as a PyPI artifact for okf-parser.
+_NPM_KINDS: Final = {"npm-parser", "npm-duckdb", "npm-native"}
+# Keep compatibility with older manifests/tests that predate the native npm
+# artifact; release_contract.py is the authority that requires the complete
+# current release set. When npm-native is present here, it must be inspected.
+_REQUIRED_NPM_KINDS: Final = {"npm-parser", "npm-duckdb"}
 _MIN_PYPI_ARTIFACTS: Final = 2  # at least one wheel + the sdist
 
 
@@ -134,7 +145,7 @@ def _artifact_index(manifest: dict[str, object]) -> tuple[str, dict[str, Artifac
         if kind in indexed:
             _fail(f"duplicate manifest artifact kind {kind!r}")
         indexed[kind] = item
-    if not _NPM_KINDS.issubset(indexed):
+    if not _REQUIRED_NPM_KINDS.issubset(indexed):
         _fail("manifest artifact set is missing an npm package")
     pypi_kinds = set(indexed) - _NPM_KINDS
     if len(pypi_kinds) < _MIN_PYPI_ARTIFACTS:
@@ -351,6 +362,15 @@ def inspect_registry_state(
         _npm_state("okf-parser", artifacts["npm-parser"], fetch, timeout),
         _npm_state("okf-parser-duckdb", artifacts["npm-duckdb"], fetch, timeout),
     ]
+    if "npm-native" in artifacts:
+        entries.append(
+            _npm_state(
+                "okf-parser-native-linux-x64",
+                artifacts["npm-native"],
+                fetch,
+                timeout,
+            )
+        )
     states = [entry["state"] for entry in entries]
     allowed = {"absent", "present_expected"}
     return {

{okf_parser-0.43.0 → okf_parser-0.45.2}/scripts/release_contract.py

@@ -1,3 +1,10 @@
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# ]
+# ///
 """Validate synchronized release metadata and artifact bytes."""
 
 from __future__ import annotations
@@ -320,11 +327,36 @@ def _verify_changelog(root: Path, version: str) -> Path:
     return path
 
 
+def _verify_rust_crates(root: Path, version: str) -> None:
+    """Check the Rust crate versions against the workspace version.
+
+    docs/releasing.md lists "the Rust crate version" among what verify-source
+    requires, but nothing read any Cargo.toml and okf-engine silently drifted
+    to 0.39.1 while the workspace published 0.45.0 (issue #172). rust-core
+    additionally pins okf-engine as an internal path dependency, so all three
+    numbers must move together.
+    """
+    for crate_root, name in ((root / "okf-engine", "okf-engine"), (root / "rust-core", "okf-core")):
+        path = crate_root / "Cargo.toml"
+        try:
+            manifest = tomllib.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, tomllib.TOMLDecodeError) as exc:
+            _fail(f"cannot read {path}: {exc}")
+        package = _mapping(manifest.get("package"), f"{path} [package]")
+        if _string(package, "version", str(path)) != version:
+            _fail(f"{name} crate version must be {version}")
+    dependencies = _mapping(manifest.get("dependencies"), "rust-core/Cargo.toml dependencies")
+    internal = _mapping(dependencies.get("okf-engine"), "rust-core okf-engine dependency")
+    if _string(internal, "version", "rust-core okf-engine dependency") != version:
+        _fail(f"rust-core internal okf-engine dependency must be {version}")
+
+
 def verify_source(root: Path, tag: str | None = None) -> SourceContract:
     """Verify package names, versions, protocol, peer range and changelog."""
     version = _project_version(root)
     _verify_npm_contract(root, version)
     _verify_protocol(root, version)
+    _verify_rust_crates(root, version)
     changelog = _verify_changelog(root, version)
     _verify_readme_action(root, version)
     if tag is not None and tag != f"v{version}":

{okf_parser-0.43.0 → okf_parser-0.45.2}/src/okf_parser/__init__.py

@@ -1,6 +1,7 @@
 """Relational inspection and validation for Open Knowledge Format bundles."""
 
 from okf_parser.bundle import Bundle, validate_path
+from okf_parser.concepts import concept, resolve_relations
 from okf_parser.edit import EditError, preview_concept_edit, write_concept_edit
 from okf_parser.engine import load_bundle
 from okf_parser.graphql_adapter import (
@@ -29,10 +30,12 @@ __all__ = [
     "ValidationReport",
     "Violation",
     "build_graphql_schema",
+    "concept",
     "export_graphql_sdl",
     "ingest_documents",
     "load_bundle",
     "preview_concept_edit",
+    "resolve_relations",
     "validate_path",
     "write_concept_edit",
 ]

{okf_parser-0.43.0 → okf_parser-0.45.2}/src/okf_parser/bundle_import.py

@@ -12,6 +12,9 @@ cannot open on its own surfaces as DuckDB's own error, unchanged.
 
 from __future__ import annotations
 
+import hashlib
+import hmac
+import json
 from io import StringIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Literal
@@ -110,12 +113,88 @@ def _matches_candidate(destination: Path, candidate: str) -> bool:
     return existing.parsed_digest == intended.parsed_digest
 
 
+def _destination_state(destination: Path) -> dict[str, str]:
+    """Return the destination state that must remain unchanged until commit."""
+    if destination.is_symlink():
+        return {"kind": "symlink", "target": str(destination.readlink())}
+    if destination.is_file():
+        return {
+            "kind": "file",
+            "sha256": hashlib.sha256(destination.read_bytes()).hexdigest(),
+        }
+    if destination.exists():
+        return {"kind": "other"}
+    return {"kind": "absent"}
+
+
+def _stable_rows(columns: Sequence[str], rows: Sequence[dict[str, object]]) -> list[list[object]]:
+    """Preserve the effective source values in a JSON-stable representation."""
+    stable: list[list[object]] = []
+    for row in rows:
+        values: list[object] = []
+        for column in columns:
+            value = row.get(column)
+            if value is None:
+                values.append(None)
+            elif isinstance(value, str):
+                values.append(["str", value])
+            else:
+                values.append([type(value).__qualname__, str(value)])
+        stable.append(values)
+    return stable
+
+
+def _preview_token(
+    *,
+    source: str,
+    concept_type: str,
+    id_column: str | None,
+    overwrite: bool,
+    on_conflict: ImportConflictPolicy,
+    columns: Sequence[str],
+    rows: Sequence[dict[str, object]],
+    destinations: dict[str, dict[str, str]],
+) -> str:
+    """Bind an import preview to its source plan and current destination state."""
+    payload = {
+        "version": 1,
+        "source": source,
+        "concept_type": concept_type,
+        "id_column": id_column,
+        "overwrite": overwrite,
+        "on_conflict": on_conflict,
+        "columns": list(columns),
+        "rows": _stable_rows(columns, rows),
+        "destinations": [[relative, destinations[relative]] for relative in sorted(destinations)],
+    }
+    encoded = json.dumps(
+        payload,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
 def _validate_options(*, overwrite: bool, on_conflict: ImportConflictPolicy) -> None:
     if overwrite and on_conflict == "verify-identical":
         message = "overwrite and on_conflict='verify-identical' are mutually exclusive"
         raise BundleImportError(message)
 
 
+def _validate_preview_token(
+    *, write: bool, preview_token: str, expected_preview_token: str | None
+) -> None:
+    """Fail closed when a reviewed import preview no longer matches current state."""
+    if (
+        write
+        and expected_preview_token is not None
+        and not hmac.compare_digest(preview_token, expected_preview_token)
+    ):
+        message = "import preview is stale; rerun preview before committing"
+        raise BundleImportError(message)
+
+
 def import_bundle(  # each argument is an independent public CLI flag.
     source: str,
     path: str,
@@ -125,6 +204,7 @@ def import_bundle(  # each argument is an independent public CLI flag.
     write: bool = False,
     overwrite: bool = False,
     on_conflict: ImportConflictPolicy = "skip",
+    expected_preview_token: str | None = None,
 ) -> dict[str, object]:
     """Materialize every row of a DuckDB-readable source as one concept document.
 
@@ -134,6 +214,11 @@ def import_bundle(  # each argument is an independent public CLI flag.
     concept value as an idempotent match and any divergence as an atomic
     conflict. `overwrite` remains an explicit replacement policy and cannot be
     combined with `verify-identical`.
+
+    Dry-runs return a deterministic ``preview_token``. When a write supplies
+    ``expected_preview_token``, source values and every relevant destination
+    must still match that reviewed preview or the call fails before any
+    filesystem mutation.
     """
     _validate_options(overwrite=overwrite, on_conflict=on_conflict)
     root = Path(path).resolve()
@@ -142,6 +227,22 @@ def import_bundle(  # each argument is an independent public CLI flag.
         message = "source column 'type' is reserved; use --type to set concept identity"
         raise BundleImportError(message)
     plan, duplicate_ids = _plan(concept_type, columns, rows, id_column)
+    destinations = {relative: _destination_state(root / relative) for relative in plan}
+    preview_token = _preview_token(
+        source=source,
+        concept_type=concept_type,
+        id_column=id_column,
+        overwrite=overwrite,
+        on_conflict=on_conflict,
+        columns=columns,
+        rows=rows,
+        destinations=destinations,
+    )
+    _validate_preview_token(
+        write=write,
+        preview_token=preview_token,
+        expected_preview_token=expected_preview_token,
+    )
     if duplicate_ids:
         return {
             "created": [],
@@ -150,6 +251,7 @@ def import_bundle(  # each argument is an independent public CLI flag.
             "matched_existing": [],
             "conflicting_existing": [],
             "duplicate_ids": list(duplicate_ids),
+            "preview_token": preview_token,
             "written": False,
         }
 
@@ -183,6 +285,7 @@ def import_bundle(  # each argument is an independent public CLI flag.
             "matched_existing": sorted(matched_existing),
             "conflicting_existing": sorted(conflicting_existing),
             "duplicate_ids": [],
+            "preview_token": preview_token,
             "written": False,
         }
 
@@ -194,6 +297,7 @@ def import_bundle(  # each argument is an independent public CLI flag.
             "matched_existing": sorted(matched_existing),
             "conflicting_existing": [],
             "duplicate_ids": [],
+            "preview_token": preview_token,
             "written": False,
         }
 
@@ -210,5 +314,6 @@ def import_bundle(  # each argument is an independent public CLI flag.
         "matched_existing": sorted(matched_existing),
         "conflicting_existing": [],
         "duplicate_ids": [],
+        "preview_token": preview_token,
         "written": True,
     }

{okf_parser-0.43.0 → okf_parser-0.45.2}/src/okf_parser/cli.py

@@ -99,6 +99,7 @@ def import_command(  # each argument is an independent public CLI flag.
     write: bool = False,
     overwrite: bool = False,
     on_conflict: ImportConflictPolicy = "skip",
+    expected_preview_token: str | None = None,
 ) -> CliResult[JsonPayload]:
     """Materialize every row of a DuckDB-readable source (CSV, Parquet, JSON) as a concept."""
     payload = import_bundle(
@@ -109,6 +110,7 @@ def import_command(  # each argument is an independent public CLI flag.
         write=write,
         overwrite=overwrite,
         on_conflict=on_conflict,
+        expected_preview_token=expected_preview_token,
     )
     failed = bool(payload["duplicate_ids"]) or bool(payload["conflicting_existing"])
     return CliResult(payload, 1 if failed else 0)
@@ -450,6 +452,7 @@ def mcp_import_write(
     id_column: str | None = None,
     overwrite: bool = False,
     on_conflict: ImportConflictPolicy = "skip",
+    expected_preview_token: str | None = None,
 ) -> dict[str, object]:
     """Commit a tabular import using the existing import service."""
     return import_bundle(
@@ -460,6 +463,7 @@ def mcp_import_write(
         write=True,
         overwrite=overwrite,
         on_conflict=on_conflict,
+        expected_preview_token=expected_preview_token,
     )