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

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

@@ -447,7 +447,7 @@ dependencies = [
 
 [[package]]
 name = "okf-core"
-version = "0.45.2"
+version = "0.45.4"
 dependencies = [
  "clap",
  "okf-engine",
@@ -457,7 +457,7 @@ dependencies = [
 
 [[package]]
 name = "okf-engine"
-version = "0.45.2"
+version = "0.45.4"
 dependencies = [
  "chrono",
  "ignore",

{okf_parser-0.45.2 → okf_parser-0.45.4}/Cargo.toml

@@ -1,5 +1,6 @@
 [workspace]
 members = ["okf-engine", "rust-core"]
+exclude = ["duckdb-extension"]
 resolver = "3"
 
 [profile.release]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okf-parser
-Version: 0.45.2
+Version: 0.45.4
 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.45.2
+  - uses: franklinbaldo/okf-parser@v0.45.4
     with:
       path: knowledge
 ```

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

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

{okf_parser-0.45.2 → okf_parser-0.45.4}/changelog/0.1.0.md

@@ -1,5 +1,5 @@
 ---
-type: ChangelogEntry
+type: Release
 title: okf-parser 0.1.0
 description: Initial release of the relational OKF validation toolkit
 ---

{okf_parser-0.45.2 → okf_parser-0.45.4}/changelog/0.2.0.md

@@ -1,5 +1,5 @@
 ---
-type: ChangelogEntry
+type: Release
 title: okf-parser 0.2.0
 description: Validate frontmatter at the parse boundary and stop single documents from aborting a run
 ---

{okf_parser-0.45.2 → okf_parser-0.45.4}/changelog/0.3.0.md

@@ -1,5 +1,5 @@
 ---
-type: ChangelogEntry
+type: Release
 title: okf-parser 0.3.0
 description: Decide ordered-list numbering while rendering, and refuse a rewrite that changes protected block structure
 ---

{okf_parser-0.45.2 → okf_parser-0.45.4}/changelog/0.4.0.md

@@ -1,5 +1,5 @@
 ---
-type: ChangelogEntry
+type: Release
 title: okf-parser 0.4.0
 description: Exclude subpaths so a mixed repository can be validated from one root
 ---

{okf_parser-0.45.2 → okf_parser-0.45.4}/changelog/0.45.2.md

@@ -5,7 +5,7 @@ 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.
+- 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. Maturin normalizes source-distribution file modes to `644`, so the restored bit applies to the repository and to clones, not inside the published sdist.
 - 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.45.4/changelog/0.45.3/correct-0-45-2-notes.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: Correct the 0.45.2 release notes
+---
+
+- Correct the 0.45.2 changelog, which claimed the restored executable bits reach consumers of the source distribution. Maturin normalizes sdist file modes to `644`; the bits apply to the repository and to clones.

okf_parser-0.45.4/changelog/0.45.3/pep723-workflow-python.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: PEP 723 for the workflows' inline Python
+---
+
+- Finish the PEP 723 migration in the workflows themselves. Standalone Python that lived as `python -c` and `python - <<PY` heredocs became three declared helpers -- `scripts/project_version.py`, `scripts/verify_wheel_scripts.py` and `scripts/release_summary.py` -- each run through `uv run --script`. The project version had five inline copies reaching for the runner's ambient interpreter, the one-unified-executable wheel check had two, and the dry run's job summary could only ever be exercised by pushing to CI. All three now have unit tests, run off CI against a downloaded release tree, and are covered by the workflow policy tests, which reject a return to inline Python. The one surviving `python -c` reads `platform.python_version()` for the manifest's build provenance, where an ephemeral script interpreter would report the wrong number.

okf_parser-0.45.4/changelog/0.45.3/uv-first-release-validation.md

@@ -0,0 +1,9 @@
+---
+type: Release Note
+title: uv-first release validation
+---
+
+- Make `uv` the Python environment/install/runner path for release validation. The platform wheel smokes in both the release workflow and the release dry run now use `astral-sh/setup-uv`, `uv venv`, and `uv pip install`; release helpers that declare PEP 723 metadata (`check_no_duckdb_link.py`, `release_contract.py`, `native_from_wheel.py`, and `registry_state.py`) run through `uv run --script` instead of a bare Python interpreter. Regression tests lock this uv-first policy into both workflows.
+- Stop depending on `rustup self uninstall` to prove that a missing wheel fails loudly. The public-index smoke now enforces `uv pip install --only-binary :all:`, which directly forbids a source fallback on every platform and avoids the macOS runner failure where Homebrew rustup refuses self-uninstallation.
+- Replace the fixed `sleep 30` and auxiliary PyPI JSON polling with retry of the real consumer operation: `uv pip install --refresh-package okf-parser --only-binary :all: okf-parser==<version>`. The gate only advances when the public index actually serves a compatible wheel to the installer, eliminating the propagation race that hit 0.45.2.
+- Keep the dry run semantically aligned with release: wheel-consumer installs are binary-only through uv, while the explicit sdist-consumer path remains allowed to build from source so that fallback is still tested deliberately rather than accidentally.

okf_parser-0.45.4/changelog/0.45.3/version-belongs-to-the-release.md

@@ -0,0 +1,8 @@
+---
+type: Release Note
+title: A version identifies a release, not a pull request
+---
+
+- Let several changes declare the same version, because that is the version they will all carry once merged. The CI gate compared each pull request's version against `origin/$BASE` and refused equality, which on a stack means comparing against the previous PR's branch: the gate itself numbered one six-deep chain 0.45.3 through 0.45.8, while two other pull requests still asked for numbers that had already shipped. The gate now enforces the invariant that actually matters -- never reuse a published version, read from the `v*.*.*` tags -- and allows the head version to equal its base.
+- Move release notes from one `changelog/X.Y.Z.md` to fragments under `changelog/X.Y.Z/`. Changes that share a version no longer compete for a single file; each contributes its own note and `scripts/changelog_notes.py` assembles them, in sorted file-name order, into the published release body. Prefix a fragment's name if you need it to sort somewhere particular. Releases up to 0.45.2 keep their flat files as an archive.
+- Stop publishing frontmatter to GitHub. `finalize` passed `changelog/X.Y.Z.md` straight to `gh release create`, so v0.45.1's release body opens with a byte-order mark and a `---` block; the assembler emits the notes alone.

okf_parser-0.45.4/changelog/0.45.4/agent-first-search-rfc.md

@@ -0,0 +1,9 @@
+---
+type: Release Note
+title: Define agent-first bundle search
+---
+
+- Propose RFC 0016 with one public `search` surface that returns compact, provenance-preserving Markdown evidence through explicitly ephemeral body-line locations such as `path.md#B35-B39`.
+- Freeze deterministic offline lexical/literal Phase 1A semantics, exact filter/profile/mode rules, whole-line compact rendering, ranking/tie-breaking, static RFC 0008 MCP effects, and cross-runtime conformance expectations without requiring embeddings, a persistent sidecar, or network access.
+- Keep local DuckDB FTS/BM25 as a non-blocking Phase 1B optimization and keep vector, hybrid, ANN, embeddings, and persistent materializations behind later profiles/phases.
+- Align retrieval with RFC 0015: structural document IR may select complete Markdown fragments, but raw AST/IR JSON is not default agent context; task success/quality gates benchmarks and actual agent-context tokens remain the primary efficiency metric.

okf_parser-0.45.4/changelog/0.45.4/atomic-import-writes.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: atomic per-document import writes
+---
+
+- Make `import --write` stage each destination and rename it into place instead of writing directly to the live Markdown path. A crash during one document write can therefore leave a temporary file but cannot leave a truncated concept at the destination; regression coverage injects a mid-write failure and verifies every committed document remains byte-identical to a clean import.

okf_parser-0.45.4/changelog/0.45.4/codebase-to-okf-lexical-containment.md

@@ -0,0 +1,8 @@
+---
+type: Release Note
+title: expose lexical containment in codebase OKF
+---
+
+- Add immediate bidirectional lexical-containment metadata to projected classes, functions, and methods, including definition-line and generated-path identity so same-name redefinitions remain distinct.
+- Add exact `--parent` lookup so agents can retrieve the immediate children of a class or callable without reopening source.
+- Keep containment explicitly syntax-level: it does not claim runtime ownership, inheritance, reachability, descriptor binding, or call dispatch.

okf_parser-0.45.4/changelog/0.45.4/codebase-to-okf-local-import-resolution.md

@@ -0,0 +1,11 @@
+---
+type: Release Note
+title: Conservative local import resolution for codebase OKF
+description: The codebase skill can now add separate source-tree import-resolution claims without rewriting syntax observations or claiming runtime dispatch
+---
+
+# Conservative local import resolution for codebase OKF
+
+Adds a PEP 723 `resolve_codebase_okf.py` enrichment recipe that maps import targets only when they match a unique projected `CodeModule` in the generated source tree.
+
+The resolver preserves `CodeImport` as immutable syntax evidence and emits separate `CodeImportResolution` concepts with explicit `source-tree-resolved` or `source-tree-partial` status, a versioned resolution method, normative type specification, deterministic regeneration and dependency-oriented query support.

okf_parser-0.45.4/changelog/0.45.4/codebase-to-okf-one-shot.md

@@ -0,0 +1,11 @@
+---
+type: Release Note
+title: One-shot codebase-to-OKF projection
+description: The codebase skill now provides one agent-facing command that generates and normatively finalizes a Python OKF bundle before returning success
+---
+
+# One-shot codebase-to-OKF projection
+
+Adds `codebase_to_okf.py`, a thin PEP 723 orchestrator over the existing Python generator and type finalizer. The default agent workflow now returns only after producer-defined type specs reach their canonical fixed point and normative validation succeeds.
+
+The lower-level generation and finalization recipes remain available for inspection and repair, while `--force` regeneration through the one-shot path remains byte-for-byte deterministic.

okf_parser-0.45.4/changelog/0.45.4/codebase-to-okf-project-manifest.md

@@ -0,0 +1,13 @@
+---
+type: Release Note
+title: project PEP 621 dependencies into OKF
+---
+
+The `codebase-to-okf` skill now includes standard Python project metadata in the one-shot projection when a PEP 621 `[project]` table is present in `pyproject.toml`.
+
+- `CodeProject` preserves authored project identity and selected PEP 621 fields.
+- `CodeDependency` preserves runtime and optional PEP 508 declarations with parsed navigation fields.
+- dependency concepts use `manifest-declared` explicitly and do not claim installation, imports, reachability, or runtime use.
+- the query recipe adds `--package` for compact dependency lookup.
+- the normative finalizer documents both new producer-defined types through canonical `docs/types/{slug}.md` specs.
+- projects without a PEP 621 `[project]` table keep the source-only projection path unchanged.

okf_parser-0.45.4/changelog/0.45.4/codebase-to-okf-self-describing-types.md

@@ -0,0 +1,11 @@
+---
+type: Release Note
+title: Self-describing codebase-to-OKF bundles
+description: Generated codebase bundles can now be finalized with canonical type specifications scaffolded through the same init lifecycle used by okf-parser itself
+---
+
+# Self-describing codebase-to-OKF bundles
+
+Adds a `finalize_codebase_okf.py` PEP 723 recipe that runs the canonical `init_bundle` service to a fixed point, authors semantics for the generated `Code*` types plus `Spec`, and validates the result with normative `docs/types/{slug}.md` coverage.
+
+The finalizer is deterministic and idempotent: it never invents specification paths, does not rewrite already-complete specs, and a second run leaves the generated bundle byte-for-byte unchanged.

okf_parser-0.45.4/changelog/0.45.4/codebase-to-okf-skill.md

@@ -0,0 +1,12 @@
+---
+type: Release Note
+title: self-contained codebase-to-OKF recipe skill
+---
+
+- Add RFC 0019, keeping source-specific extraction out of `okf-parser` core and defining typed recipe skill directories as the preferred boundary for deterministic source-to-OKF adapters.
+- Add `skills/codebase-to-okf/SKILL.md` plus bundled PEP 723 generation and query recipes under `scripts/`, keeping agent instructions compact while recipe-only dependencies stay outside the package runtime.
+- Extract Python modules, classes, functions, methods, imports, signatures, parameters, returns, docstrings, decorators, bases, class fields and explicit `CodeCall` syntax observations into deterministic derived OKF.
+- Preserve epistemic boundaries by marking calls and imports `syntactic-unresolved`; name-matched call targets are navigation candidates rather than dispatch claims.
+- Add compact code-aware lookup by symbol, caller, callee, source and producer-defined type on top of the public generic `load_bundle()` API, without adding code semantics to parser core; compact JSON is the default so agents can decide whether a source read is still necessary before paying for it.
+- Keep the standalone recipes under the repository's normal Ruff quality rules, with only the explicit `T201` exception appropriate to command-line output rather than a blanket recipe lint exemption.
+- Test the skill as typed OKF knowledge and both bundled recipes as executable code, including rich metadata, same-name redefinitions, code-aware lookup, conformant output and byte-for-byte deterministic regeneration.

okf_parser-0.45.4/changelog/0.45.4/duckdb-extension-concepts-slice.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: first native DuckDB extension slice
+---
+
+- Add the first RFC 0010 implementation slice: an experimental Rust loadable DuckDB extension exposing `okf_concepts(root)` directly from the shared `okf-engine`, emitting DuckDB data chunks without subprocess/whole-bundle JSON transport and keeping the evolving extension toolchain isolated from the stable workspace release graph.

okf_parser-0.45.4/changelog/0.45.4/duckdb-extension-read-surface.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: complete native DuckDB read surface
+---
+
+- Extend the RFC 0010 DuckDB extension slice with `okf_links(root)`, `okf_reserved(root)` and `okf_diagnostics(root)` alongside `okf_concepts(root)`, preserving unresolved links, reserved documents and document-level diagnostics as typed SQL rows while keeping root/configuration failures as table-function errors.

okf_parser-0.45.4/changelog/0.45.4/git-commit-envelope.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: subject-first Git commit envelopes
+---
+
+- Implement the first RFC 0009 Git adapter slice: parse and validate subject-first `--- okf` commit-message envelopes, preserve plain commits with an effective `type: Commit`, reject adapter-owned metadata collisions with stable diagnostics, expose an `okf-commit-msg` hook command, and pin Python/TypeScript parity with shared conformance vectors and canonical digests.

okf_parser-0.45.4/changelog/0.45.4/projection-documents.md

@@ -0,0 +1,12 @@
+---
+type: Release Note
+title: projection documents, parsed and resolved
+---
+
+- Recognize `type: Projection` documents in a bundle (RFC 0018 section 5). A projection names one root concept type and, in `include`, the declared relations to traverse; each `relation` is written `FromType.field` and must resolve to a `FOREIGN KEY` the bundle's `okf.schema.sql` already declares. A projection composes what the relational contract states and cannot invent a relationship.
+- Resolve each relation's direction from RFC 0007's rule that N:1 is the primitive: a key *pointing at* the root becomes a list on the root, a key *on* the root becomes a single value. A self-reference is written from the root's own side and therefore reads as single.
+- Resolve a composite foreign key from any one of its participating columns, so the case that standalone `--refs=embed` refuses is the case a projection answers — the member's `as` is the name that was missing.
+- Refuse, with errors that name the projection: an unknown root, a name colliding with a concept type, a duplicate projection or member name, a relation that is not `FromType.field`, a relation the relational contract does not declare, a relation that connects two types neither of which is the root, and a projection document in a bundle with no relational schema to resolve it against. `optional: true` is the only member-level modifier recognized; any other key is an error rather than a silent no-op, so a mistyped `as` cannot pass for composition.
+- Keep projections out of the compiled concept types: a bundle with projection documents no longer exports a `Projection` schema whose fields are `name`, `root` and `include`.
+
+Parsing and resolution only. Compiling a resolved projection into a `TypeContract` and exporting it through `--format` is the next step of the same RFC.

okf_parser-0.45.4/changelog/0.45.4/referential-schema-export-embed-mode.md

@@ -0,0 +1,10 @@
+---
+type: Release Note
+title: referential schema export, embed mode
+---
+
+- Add `schema --refs=embed`, the second half of RFC 0018's export: a declared reference stops being a scalar and becomes the referenced schema itself. It is emitted **by name**, never re-inlined — `$ref` into the exported `defs` pool for JSON Schema, the sibling `const` for Zod, and the sibling model for Pydantic — so one change to a type reaches every schema that references it in the same regeneration.
+- Order Zod declarations by dependency, since a `const` cannot be read before it is declared, and close a cycle with `z.lazy(() => Schema)` on the one edge that ordering cannot satisfy. A self-referencing type is the minimal case and is covered by the corpus.
+- Emit Pydantic forward references with postponed annotations and a trailing `model_rebuild()`, and only when an embedded reference actually needs them: a bundle without cycles generates exactly the module it generated before. The generated module is executed in the tests, not merely string-matched, so a cyclic model is proven to import and validate.
+- Refuse `--refs=embed` on a composite foreign key with an error that names the constraint and points at projections: embedding replaces the key's columns with one member, and naming that member from N columns would put a naming convention in the parser. `--refs=key` continues to support composite keys.
+- Refuse `--refs=embed` without `--relational-schema`, which has nothing to embed.

okf_parser-0.45.4/changelog/0.45.4/referential-schema-export-key-mode.md

@@ -0,0 +1,10 @@
+---
+type: Release Note
+title: referential schema export, key mode
+---
+
+- Implement the first half of RFC 0018: `schema --relational-schema PATH` reads the bundle's `okf.schema.sql` and compiles every field participating in a declared `FOREIGN KEY` to a reference node instead of to the bare scalar it carries. Composition is read from the RFC 0007 contract that already exists — no second place to declare that two types are related, and no naming or folder convention consulted.
+- Publish the reference in each format's own idiom: JSON Schema gains `x-okf-references` (target type, the constraint's columns in authored order, the referenced columns, and this field's position in the key), Zod gains a `.describe("references Type(column)")` that leaves `z.infer` untouched, and Pydantic carries the same payload in `Field(json_schema_extra=...)`. The field keeps the scalar type it always had: under key mode a reference is a type-level fact about the value, not a promise that the consumer holds the referenced document.
+- Support composite foreign keys, which `ForeignKeyConstraint` has described since RFC 0007: every participating column carries the whole constraint and its own position, so a consumer can reassemble the key without guessing its order.
+- Keep the whole feature opt-in and default-off. Without `--relational-schema` the exported JSON Schema, Zod and Pydantic are byte-identical to before, which the regression corpus asserts directly. A relative path resolves against the bundle root, matching `check --relational-schema`.
+- Report, rather than silently skip, a declared foreign-key column that no document of its type carries, and a column claimed by two foreign keys.

okf_parser-0.45.4/changelog/0.45.4/referential-schema-export.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: referential schema export proposal
+---
+
+- Add RFC 0018, proposing referential schema export and declared projections: `schema` learns to read the bundle's `okf.schema.sql` so a field participating in a declared foreign key compiles to a reference instead of a closed scalar, and an optional `type: Projection` document composes a root type with declared relations. Both are opt-in; without the new flag and without projection documents the export is unchanged. The RFC also proposes emitting `export type X = z.infer<typeof XSchema>` from the Zod renderer, which removes the hand-written barrel every TypeScript consumer maintains today.

okf_parser-0.45.4/changelog/0.45.4/refs-depth-and-composite-keys.md

@@ -0,0 +1,7 @@
+---
+type: Release Note
+title: reference depth and composite-key rules
+---
+
+- Amend RFC 0018 with the two controls its first draft left open. `--refs=embed` stays a per-run binary mode rather than a per-field selector: a projection is where per-member composition is declared. Depth moves to projections, where it is answerable — a flat export emits one schema per concept type and every type is a root there, so bounding hops would need two variants of the same contract; a projection has exactly one root, and a member beyond its bound degrades to the reference's key form instead of being dropped.
+- Settle composite foreign keys, which `ForeignKeyConstraint` has described since RFC 0007 and which the motivating bundle needs on its first reference: `--refs=key` supports them, projections embed them under the member's `as` name, and standalone `--refs=embed` rejects them with a normative error that names the constraint and points at projections. Naming a composed member from N columns would put a naming convention in the parser, which the RFC's first decision forbids.

okf_parser-0.45.4/changelog/0.45.4/rfc-0015-canonical-markdown-ir.md

@@ -0,0 +1,9 @@
+---
+type: Release Note
+title: Define the canonical Markdown document model
+---
+
+- Propose RFC 0015: make the Rust engine the authoritative Markdown parser while keeping raw `mdast` private behind an OKF-owned, versioned document protocol.
+- Define frozen/closed Pydantic and TypeScript boundary models, source spans over a normalized parser snapshot, exact-source guarding through `source_digest`, and an internal `SourceMap` for lossless BOM/newline-aware edits.
+- Keep generated RFC 0001 Pydantic models focused on producer-authored frontmatter, keep `Bundle` and relational records compact, and make full AST serialization opt-in.
+- Add convergence gates with #182/#183 performance fast paths, #189 structural retrieval, and #104 Git/provenance ownership.

okf_parser-0.45.4/changelog/0.45.4/rfc0009-git-commits.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: Git commits as OKF proposal
+---
+
+- Accept RFC 0009 defining Git commit messages as an explicit OKF source-adapter surface: subject-first `--- okf` envelopes preserve ordinary Git subjects, plain commits remain representable as `type: Commit`, Git object/provenance identity stays adapter-owned, and `parsed_digest` covers the effective semantic OKF projection rather than Git transport metadata.

okf_parser-0.45.4/changelog/0.45.4/rfc0010-native-duckdb-extension.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: native DuckDB extension proposal
+---
+
+- Propose RFC 0010 for a loadable DuckDB extension backed by the shared `okf-engine`: keep OKF semantics DuckDB-independent, expose concepts/links/reserved/diagnostics as typed table functions, retain Python/TypeScript/CLI fallbacks, and treat projection pushdown, bounded chunking, cancellation and Community Extension distribution as explicit implementation gates.

okf_parser-0.45.4/changelog/0.45.4/rfc0011-tracked-migrations.md

@@ -0,0 +1,6 @@
+---
+type: Release Note
+title: tracked bundle migrations proposal
+---
+
+- Propose RFC 0011 for idempotent, ledger-backed bundle migrations that reuse the RFC 0005 relational write contract and record each migration as an ordinary `type: Migration` OKF concept. The design also makes atomic creation of new candidate files a shared write primitive so migrations and imports can converge on one staging/validation/conflict path.

okf_parser-0.45.4/changelog/0.45.4/rfc0015-rust-markdown-ast.md

@@ -0,0 +1,11 @@
+---
+type: Release Note
+title: Propose RFC 0015, a canonical Rust Markdown AST
+---
+
+Documentation/RFC release; no runtime behavior changes.
+
+- Propose RFC 0015: make the Rust engine the authoritative Markdown parser while keeping raw `mdast` private behind an OKF-owned, versioned document protocol.
+- Define frozen/closed Pydantic and TypeScript boundary models, source spans over a normalized parser snapshot, exact-source guarding through `source_digest`, and an internal `SourceMap` for lossless BOM/newline-aware edits.
+- Keep generated RFC 0001 Pydantic models focused on producer-authored frontmatter, keep `Bundle` and relational records compact, and make full AST serialization opt-in.
+- Add convergence gates with #182/#183 performance fast paths, #189 structural retrieval, and #104 Git/provenance ownership.

okf_parser-0.45.4/changelog/0.45.4/rfc0017-fact-profile.md

@@ -0,0 +1,16 @@
+---
+type: Release Note
+title: Draft RFC 0017, the provider-local fact profile
+---
+
+- Draft RFC 0017, the `fact` profile, scoped explicitly to native `.fact/`
+  contexts so plain OKF keeps the identity, reserved filenames and vocabulary
+  the base format and RFC 0012 already pin. A markerless directory is read as a
+  compatibility view, and retiring `index.md`/`log.md` or renaming
+  `bundle`/`concept` stays profile-local until a migration of its own.
+- Reconcile the profile's stable fact identity with RFC 0012 by defining
+  `.fact/` as a distinct provider rather than a reinterpretation of the
+  filesystem provider. Identity still comes from the provider and never from
+  content: the id is authored, not inferred from equal digests.
+- Add `examples/minimal`, the smallest bundle `check` accepts as conformant,
+  validated by the repository's own `check` run.

okf_parser-0.45.4/changelog/0.45.4/rfc0018-projection-export.md

@@ -0,0 +1,9 @@
+---
+type: Release Note
+title: projection contracts export across schema formats
+---
+
+- Export resolved RFC 0018 `Projection` contracts through JSON Schema, Zod, and Pydantic while preserving every field of the root contract.
+- Compose each declared member under its authored `as` name by sibling-schema reference rather than structural re-inline; 1:N members become lists, singular relations remain singular, and composite foreign keys are supported because the projection supplies the composed member name.
+- Keep undeclared references on the root in key form while projection-declared members are embedded by name, so the projection remains the sole control over composition.
+- Treat `optional: true` as a nullable composed member, matching RFC 0018, and publish JSON Schema `$defs` whenever projection references require them even under the default flat key mode.

okf_parser-0.45.4/changelog/0.45.4/type-specifications.md

@@ -0,0 +1,18 @@
+---
+type: Release Note
+title: The repository specifies its own concept types
+---
+
+- Add a specification document for every concept type in use, at the
+  `docs/types/{slug}.md` path `--require-spec` derives, and run the rule
+  normatively in CI. The flag shipped in 0.14.0 and the repository that ships it
+  had never run it; a new type without a specification now fails the build
+  instead of passing unnoticed.
+- Migrate `changelog/0.1.0.md` through `0.4.0.md` from `ChangelogEntry` to
+  `Release`. Writing both specifications forced the question the split had been
+  hiding: same directory, same fields, same meaning, so the earlier four were
+  drift left behind by the rename at 0.5.0 rather than a second type.
+- Move the 0.45.4 release notes into `changelog/0.45.4/` as a fragment. The
+  version arrived while the flat-file format was being retired, and
+  `changelog_notes.py` assembles a release only from its fragment directory, so
+  the notes would not have reached the published body.

okf_parser-0.45.4/conformance/git-commit-messages.json

@@ -0,0 +1,84 @@
+{
+  "valid": [
+    {
+      "name": "plain",
+      "source": "Fix the thing\n\nNarrative.\n",
+      "subject": "Fix the thing",
+      "authored_metadata": {},
+      "effective_frontmatter": {"type": "Commit", "title": "Fix the thing"},
+      "body": "Narrative.\n",
+      "has_envelope": false,
+      "source_digest": "sha256:a57c5b47db88bb64e3cdeff8c503465b010f57746f210ad0e5e9aff0f888e4b6",
+      "parsed_digest": "okf-parsed-v1-jcs-sha256:c19c4c2520f68da420c1ba1cfd5871f836fbeff99df1ebdba51509fc57a7ea6e",
+      "formatted": "Fix the thing\n\nNarrative.\n"
+    },
+    {
+      "name": "structured",
+      "source": "Publish parser history\n\n--- okf\ntype: Post\npublish: true\ntags:\n  - git\n  - okf\n---\n\nHello **history**.\n",
+      "subject": "Publish parser history",
+      "authored_metadata": {"type": "Post", "publish": "true", "tags": ["git", "okf"]},
+      "effective_frontmatter": {"type": "Post", "publish": "true", "tags": ["git", "okf"], "title": "Publish parser history"},
+      "body": "Hello **history**.\n",
+      "has_envelope": true,
+      "source_digest": "sha256:7f223b8850136874d8218f55a819e5df5dab385a4c5a8e07030e336248fcd6c9",
+      "parsed_digest": "okf-parsed-v1-jcs-sha256:d27af18923c8a5e99d5925af51d527797f5c574bf9158a8c903dde1b53349e47",
+      "formatted": "Publish parser history\n\n--- okf\n\"publish\": \"true\"\n\"tags\": [\"git\",\"okf\"]\n\"type\": \"Post\"\n---\n\nHello **history**.\n"
+    },
+    {
+      "name": "subject-only",
+      "source": "Legacy subject only",
+      "subject": "Legacy subject only",
+      "authored_metadata": {},
+      "effective_frontmatter": {"type": "Commit", "title": "Legacy subject only"},
+      "body": "",
+      "has_envelope": false,
+      "source_digest": "sha256:1f2874fbac03a8c04e8f71b551320bb1006087b1eee542f87d5ea68837ab62ca",
+      "parsed_digest": "okf-parsed-v1-jcs-sha256:508d433a377922534b97a511103f7c97f44171a5b9f24290ecd0f16ecc2e05fa",
+      "formatted": "Legacy subject only"
+    },
+    {
+      "name": "conventional-subject",
+      "source": "feat(parser): preserve subjects\n\nBody.",
+      "subject": "feat(parser): preserve subjects",
+      "authored_metadata": {},
+      "effective_frontmatter": {"type": "Commit", "title": "feat(parser): preserve subjects"},
+      "body": "Body.",
+      "has_envelope": false,
+      "source_digest": "sha256:4fee7cb6063d4e4f8b07a02697f2427f83fb733b2198712935d748ffcd294ea0",
+      "parsed_digest": "okf-parsed-v1-jcs-sha256:a72a4f8baa3ca2011dbf1554013075157c35bf3a4cc476b376cfaad2d346bc1f",
+      "formatted": "feat(parser): preserve subjects\n\nBody."
+    }
+  ],
+  "invalid": [
+    {
+      "name": "empty-subject",
+      "source": "\n\nBody",
+      "code": "GIT_MESSAGE_EMPTY_SUBJECT"
+    },
+    {
+      "name": "unterminated-envelope",
+      "source": "Subject\n\n--- okf\ntype: Change\n",
+      "code": "GIT_MESSAGE_UNTERMINATED_ENVELOPE"
+    },
+    {
+      "name": "reserved-title",
+      "source": "Subject\n\n--- okf\ntitle: Another title\n---",
+      "code": "GIT_MESSAGE_RESERVED_KEY"
+    },
+    {
+      "name": "invalid-type",
+      "source": "Subject\n\n--- okf\ntype:\n  - Change\n---",
+      "code": "GIT_MESSAGE_TYPE"
+    },
+    {
+      "name": "missing-body-separator",
+      "source": "Subject\n\n--- okf\ntype: Change\n---\nBody",
+      "code": "GIT_MESSAGE_BODY_SEPARATOR"
+    },
+    {
+      "name": "duplicate-envelope",
+      "source": "Subject\n\n--- okf\ntype: Change\n---\n\nBody\n--- okf\n",
+      "code": "GIT_MESSAGE_DUPLICATE_ENVELOPE"
+    }
+  ]
+}

{okf_parser-0.45.2 → okf_parser-0.45.4}/docs/cli.md

@@ -126,7 +126,7 @@ MCP tool: `graph`.
 ## `schema`
 
 ```bash
-uv run okf-parser schema path/to/bundle [--format json|zod|pydantic|graphql] [--infer-types] [--cast FIELD]... [--spec-template TEMPLATE] [--exclude PATTERN]... [--zod-import zod|astro]
+uv run okf-parser schema path/to/bundle [--format json|zod|pydantic|graphql] [--infer-types] [--cast FIELD]... [--spec-template TEMPLATE] [--exclude PATTERN]... [--zod-import zod|astro] [--relational-schema PATH] [--refs key|embed]
 ```
 
 Exports the bundle's shared frontmatter contract as JSON Schema, Zod source,
@@ -159,6 +159,21 @@ multiline form rather than relying on a later formatter pass.
 - `--spec-template TEMPLATE` — derive each type's specification path and, when
   present, read the sibling `.schema.sql` declaration introduced by RFC 0006.
   The template must contain `{slug}`.
+- `--relational-schema` — read the bundle's `okf.schema.sql` (RFC 0007) and
+  compile every field participating in a declared `FOREIGN KEY` to a reference
+  (RFC 0018). A relative path resolves against the bundle root, same as
+  `check --relational-schema`. JSON Schema publishes the constraint under
+  `x-okf-references`, Zod describes it, and Pydantic carries it in
+  `json_schema_extra`; the field keeps the scalar type it already had. Without
+  the flag, output is unchanged. `--format graphql` ignores it for now.
+- `--refs` — how a declared reference is exported. `key` (default) keeps the
+  scalar and publishes the constraint as metadata. `embed` replaces the field
+  with the referenced schema **by name**: `$ref` into `defs` for JSON Schema,
+  the sibling `const` for Zod (declared in dependency order, with `z.lazy` on a
+  cycle), and the sibling model for Pydantic (with postponed annotations and
+  `model_rebuild()` when a forward reference is needed). `embed` requires
+  `--relational-schema`, and refuses a composite key: embedding replaces N
+  columns with one member, and only a projection can name it.
 - `--zod-import` — only meaningful with `--format zod`; choose the `zod` or
   `astro:content` import style.
 

{okf_parser-0.45.2 → okf_parser-0.45.4}/docs/releasing.md

@@ -53,11 +53,36 @@ Before building, `scripts/release_contract.py verify-source` requires all of the
 - versions in the npm manifests;
 - `PROTOCOL_VERSION` in `typescript/src/version.ts`;
 - the `okf-parser` peer range in the DuckDB adapter;
-- `changelog/X.Y.Z.md` frontmatter title;
+- at least one release-note fragment in `changelog/X.Y.Z/`;
 - an optional stable tag, exactly `vX.Y.Z`.
 
 Prereleases are deliberately rejected until npm dist-tag policy is implemented.
 
+## Version numbers and release notes
+
+A version number identifies a **release**, not a pull request. Several changes may declare the same number, because that is the version they will all carry once they merge. A stack of pull requests should therefore share one version rather than climbing by one at every level -- the CI gate used to force that climb, by comparing each head against its base, and produced chains numbered 0.45.3 through 0.45.8 that nobody intended.
+
+The gate now checks the invariant that matters: the declared version must outrank every published `v*.*.*` tag. It may equal the base's version, and it may not regress below it.
+
+Each change contributes its own note to `changelog/X.Y.Z/`, so changes sharing a version never compete for one file:
+
+```text
+changelog/
+├── 0.45.2.md              # releases up to 0.45.2 keep their flat file
+└── 0.45.3/
+    ├── correct-0-45-2-notes.md
+    ├── pep723-workflow-python.md
+    └── uv-first-release-validation.md
+```
+
+A fragment is a `type: Release Note` concept with a title and a body of bullets. `scripts/changelog_notes.py X.Y.Z` assembles them, in sorted file-name order, into the body `finalize` publishes as the GitHub Release; prefix a file name if a fragment must sort somewhere particular. The assembler strips frontmatter, which the old `--notes-file changelog/X.Y.Z.md` did not -- v0.45.1's release body still opens with a byte-order mark and a `---` block.
+
+Preview a release's notes at any time:
+
+```bash
+uv run --script scripts/changelog_notes.py "$(uv run --script scripts/project_version.py)"
+```
+
 ## Python packaging
 
 The root project uses Maturin as its PEP 517 backend with `bindings = "bin"`. The Python import package and PyPI distribution remain `okf_parser` and `okf-parser`; the sole installed binary target is `okf-parser`.

okf_parser-0.45.4/docs/types/architecture.md

@@ -0,0 +1,27 @@
+---
+type: Spec
+title: Architecture
+description: A document recording a structural boundary the implementation is expected to hold
+---
+
+# Architecture
+
+An `Architecture` concept records a structural rule the implementation is
+expected to hold, in enough detail that a pull request can be judged against it.
+
+The single concept of this type is [`docs/architecture.md`](../architecture.md),
+which draws the boundary between the strict authored-OKF core and source
+adapters.
+
+## Frontmatter
+
+- `type` — always `Architecture`.
+- `title` — the boundary being drawn.
+
+`description` is optional here and the existing document omits it.
+
+## Distinguished from Documentation
+
+`Documentation` explains how to use what exists. `Architecture` constrains what
+may be built. A rule that no reviewer would cite when rejecting a change is
+documentation, not architecture.