From f5ea4beb4942066e9433f70aa44363e837c45038 Mon Sep 17 00:00:00 2001
From: Fritz Kunstler <36011164+dfkunstler@users.noreply.github.com>
Date: Mon, 16 Nov 2026 21:00:14 -0500
Subject: [PATCH] chore: move the spec pin to v0.8.0+oscal.1.2.3
Move SPEC_ARTIFACT_VERSION and SPEC_ARTIFACT_SHA256 to the 0.8.0 release
of the spec store. The regenerated models.py is unchanged.
The 0.8.0 corpus adds cases for contract changes that the binding does not
implement yet. List them as strict expected failures, each tied to its
tracking issue (#58, #59, #61, #62, #63, #69). Mark
test_every_category_is_mapped as a strict xfail until the read-error and
builder-error categories are mapped.
Closes #67
---
.agents/summary/architecture.md | 6 ++---
.agents/summary/components.md | 2 +-
.agents/summary/dependencies.md | 2 +-
.agents/summary/index.md | 4 +--
.agents/summary/review_notes.md | 2 +-
.agents/summary/workflows.md | 2 +-
AGENTS.md | 2 +-
DEVELOPING.md | 2 +-
scripts/spec_artifact.py | 4 +--
tests/support/expected_failures.py | 40 ++++++++++++++++++++++++++++++
tests/test_conformance.py | 5 ++++
tests/test_spec_artifact_script.py | 4 +--
12 files changed, 60 insertions(+), 15 deletions(-)
diff --git a/.agents/summary/architecture.md b/.agents/summary/architecture.md
index c7c6abc..787dc57 100644
--- a/.agents/summary/architecture.md
+++ b/.agents/summary/architecture.md
@@ -11,7 +11,7 @@ There is no network server, no persistence layer, and no long-running process. T
```mermaid
graph TB
subgraph L0["Layer 0 — Schema (input)"]
- S["oscal_complete_schema.json + names.json
(pinned spec artifact 0.7.0+oscal.1.2.3)"]
+ S["oscal_complete_schema.json + names.json
(pinned spec artifact 0.8.0+oscal.1.2.3)"]
end
subgraph L1["Layer 1 — Generated models"]
BASE["v1/_base.py
OscalBaseModel (hand-written)"]
@@ -81,8 +81,8 @@ The top-level submodule paths get real files — `oscal_bindings/models.py`, `os
```mermaid
flowchart LR
- N["spec artifact 0.7.0+oscal.1.2.3
names.json (sha256-pinned)"] -->|"manifest.py
validate"| H
- A["spec artifact 0.7.0+oscal.1.2.3
oscal_complete_schema.json"] --> H["hoist_names.py"]
+ N["spec artifact 0.8.0+oscal.1.2.3
names.json (sha256-pinned)"] -->|"manifest.py
validate"| H
+ A["spec artifact 0.8.0+oscal.1.2.3
oscal_complete_schema.json"] --> H["hoist_names.py"]
A --> C
H --> HS["build/codegen/oscal_complete_schema.json
(each manifest site = definitions/<Name>)"]
HS -->|"datamodel-codegen"| B["build/codegen/models.py
(raw: manifest-named classes,
RootModel scalars)"]
diff --git a/.agents/summary/components.md b/.agents/summary/components.md
index f9857cc..ff8fa94 100644
--- a/.agents/summary/components.md
+++ b/.agents/summary/components.md
@@ -119,7 +119,7 @@ Not part of the installed package. `scripts/` is not a package: a script imports
| File | Responsibility | Notable symbols |
|------|----------------|-----------------|
-| `spec_artifact.py` | The one pin of the spec artifact (`0.7.0+oscal.1.2.3` + sha256), shared by `generate` and the tests; cache `tests/.corpus_cache/`. The artifact supplies the complete OSCAL schema (`artifact_paths(...).schema`), `names.json`, and the corpus, and the pin is the only selector of the OSCAL release | `SPEC_ARTIFACT_VERSION`, `SPEC_ARTIFACT_SHA256`, `SPEC_ARTIFACT`, `OSCAL_RELEASE`, `ensure_spec_artifact`, `artifact_paths`, `ArtifactPaths` |
+| `spec_artifact.py` | The one pin of the spec artifact (`0.8.0+oscal.1.2.3` + sha256), shared by `generate` and the tests; cache `tests/.corpus_cache/`. The artifact supplies the complete OSCAL schema (`artifact_paths(...).schema`), `names.json`, and the corpus, and the pin is the only selector of the OSCAL release | `SPEC_ARTIFACT_VERSION`, `SPEC_ARTIFACT_SHA256`, `SPEC_ARTIFACT`, `OSCAL_RELEASE`, `ensure_spec_artifact`, `artifact_paths`, `ArtifactPaths` |
| `pinned_archive.py` | Stdlib-only, cross-process-locked download (HTTPS only, HTTPS-only redirects, 64 MiB body cap), sha256 check before extraction, tar-slip-safe extraction with the `data` filter (Python 3.11.4+), atomic publish | `PinnedArchive`, `ensure_pinned_archive`, `http_get`, `build_https_opener`, `CorpusError`, `ResponseTooLargeError`, `FileLock` |
| `manifest.py` | Validates `names.json`: JSON Schema (`jsonschema-rs`), format/release, schema sha256 against the schema bytes, unique names, resolvable pointers, type references | `validate_manifest`, `load_validated_manifest(paths, *, schema_bytes=None, schema_path=None)` (no bytes and no path means `paths.schema`), `read_schema_bytes`, `ManifestError` |
| `hoist_names.py` | Reads the artifact schema from `paths.schema` one time, and writes `build/codegen/oscal_complete_schema.json`, in which each manifest site is `definitions/` with a `$ref` at the site | `hoist`, `HoistError`, `OUTPUT` |
diff --git a/.agents/summary/dependencies.md b/.agents/summary/dependencies.md
index 8ec80f3..43ff5a3 100644
--- a/.agents/summary/dependencies.md
+++ b/.agents/summary/dependencies.md
@@ -64,7 +64,7 @@ The pin is the only selector of the schema and its release. Codegen reads the ho
## Spec Artifact (not a package dependency)
-`scripts/spec_artifact.py` pins the spec artifact of [cairn-proofs/oscal-bindings-specs](https://github.com/cairn-proofs/oscal-bindings-specs) (`0.7.0+oscal.1.2.3`) by sha256. It holds the complete OSCAL JSON Schema, the naming manifest (`names.json` and its JSON Schema), and the conformance corpus. `hatch run generate` and `hatch test` share the pin and the cache `tests/.corpus_cache/`, so a cold cache needs network access once. An sdist checkout needs network access too, to run `generate`.
+`scripts/spec_artifact.py` pins the spec artifact of [cairn-proofs/oscal-bindings-specs](https://github.com/cairn-proofs/oscal-bindings-specs) (`0.8.0+oscal.1.2.3`) by sha256. It holds the complete OSCAL JSON Schema, the naming manifest (`names.json` and its JSON Schema), and the conformance corpus. `hatch run generate` and `hatch test` share the pin and the cache `tests/.corpus_cache/`, so a cold cache needs network access once. An sdist checkout needs network access too, to run `generate`.
## Dependency Risk Notes
diff --git a/.agents/summary/index.md b/.agents/summary/index.md
index 6f99ba0..abdbcb9 100644
--- a/.agents/summary/index.md
+++ b/.agents/summary/index.md
@@ -46,14 +46,14 @@ The implementation lives in the major-version package **`oscal_bindings.v1`**; t
- **8 OSCAL document types:** Catalog, Profile, Component Definition, System Security Plan, Assessment Plan, Assessment Results, Plan of Action and Milestones, Mapping Collection.
- **Layout:** implementation under `src/oscal_bindings/v1/`; top-level package re-exports it through explicit alias modules at `oscal_bindings/models.py`, `oscal_bindings/parser.py`, `oscal_bindings/extensions/__init__.py`.
-- **Active schema:** `oscal_complete_schema.json` of the spec artifact pinned in `scripts/spec_artifact.py` (`0.7.0+oscal.1.2.3`, by sha256). The repo holds no copy of the schema. The pin is the only selector of the schema and its release.
+- **Active schema:** `oscal_complete_schema.json` of the spec artifact pinned in `scripts/spec_artifact.py` (`0.8.0+oscal.1.2.3`, by sha256). The repo holds no copy of the schema. The pin is the only selector of the schema and its release.
- **`__oscal_schema_version__`** (`"1.2.3"`) on `oscal_bindings.v1`, re-exported at the top level, records the exact release the models came from.
- **Entry points:** `parse_oscal`, `parse_oscal_file`, 8 typed `parse_*` functions, `serialize_oscal`, `validate_oscal`, `OscalDoc`, `make_hash`/`make_rlink`/`make_resource`, `validate_element`/`get_supported_element_types`.
- **Parsers accept `str | bytes`;** bytes skips a UTF-8 decode (useful for HTTP/S3/file byte-sources).
- **`v1/models.py` is GENERATED** by `scripts/hoist_names.py` + `datamodel-codegen` + `scripts/postprocess_models.py`. Change the hoist/post-processor (or the store manifest for names) and run `hatch run generate` — never hand-edit. A cold cache needs network access. (`oscal_bindings/models.py` at the top level is a hand-written alias module, not generated.)
- **`v1/__init__.py` only re-exports** — the entire public API is visible there; the top level derives its `__all__` from it.
- **Extensions pattern:** new helpers go in `src/oscal_bindings/v1/extensions/`, re-exported up through `v1/extensions/__init__.py` then `v1/__init__.py`.
-- **Names come only from `names.json`** of the spec artifact pinned in `scripts/spec_artifact.py` (`0.7.0+oscal.1.2.3`). The hoist makes each manifest site a named definition; post-processor guards fail on any name outside the manifest. Never rename in the post-processor.
+- **Names come only from `names.json`** of the spec artifact pinned in `scripts/spec_artifact.py` (`0.8.0+oscal.1.2.3`). The hoist makes each manifest site a named definition; post-processor guards fail on any name outside the manifest. Never rename in the post-processor.
- **Namespaces are major-scoped** (`v1`); minor-version namespacing was considered and rejected on compatibility-boundary grounds. OSCAL 2.0 is the trigger for a second version package (see `DEVELOPING.md` Key Design Decisions).
- **Exceptions:** `OscalParseError` (has `.errors`), `OscalAccessError`.
diff --git a/.agents/summary/review_notes.md b/.agents/summary/review_notes.md
index 355bfd2..ac5b117 100644
--- a/.agents/summary/review_notes.md
+++ b/.agents/summary/review_notes.md
@@ -33,7 +33,7 @@ No contradictions found across the document set.
| `OscalDoc` facade incl. `assessment_period()` | Complete | Including nested-task walking and AP/AR-only constraint |
| Builders | Complete | Including `document_ids` validation at construction and the `media-type` alias |
| Element validation | Complete | `_ELEMENT_MAP` derivation explained |
-| Code generation + post-processing | Complete | Manifest validation, the hoist and its guards, the post-processor steps and its three guards against the manifest, and the CLI contracts. The pipeline takes every name from the naming manifest (spec artifact `0.7.0+oscal.1.2.3`, package version 0.4.0); these docs describe that pipeline only |
+| Code generation + post-processing | Complete | Manifest validation, the hoist and its guards, the post-processor steps and its three guards against the manifest, and the CLI contracts. The pipeline takes every name from the naming manifest (spec artifact `0.8.0+oscal.1.2.3`, package version 0.4.0); these docs describe that pipeline only |
| Version layout + import paths | Complete | Version package, top-level re-exports, alias modules, and the import-path guidance are covered in architecture.md, components.md, and interfaces.md |
| Schema refresh procedure | Complete | workflows.md §1c documents how to move the spec artifact pin and what a reviewer checks |
| Dependencies / toolchain / Python versions | Complete | Runtime, codegen, dev, build tooling all covered |
diff --git a/.agents/summary/workflows.md b/.agents/summary/workflows.md
index 890c9e3..a00f992 100644
--- a/.agents/summary/workflows.md
+++ b/.agents/summary/workflows.md
@@ -7,7 +7,7 @@ the naming manifest (`names.json`) of the pinned spec artifact. The binding hold
```mermaid
flowchart TD
- A["hatch run generate"] --> P["scripts/spec_artifact.py pin
0.7.0+oscal.1.2.3 (sha256)
cache: tests/.corpus_cache/"]
+ A["hatch run generate"] --> P["scripts/spec_artifact.py pin
0.8.0+oscal.1.2.3 (sha256)
cache: tests/.corpus_cache/"]
P --> M["scripts/manifest.py
validate names.json"]
M -->|"invalid"| X["non-zero exit,
nothing written"]
M --> H["python scripts/hoist_names.py
artifact oscal_complete_schema.json
→ build/codegen/oscal_complete_schema.json"]
diff --git a/AGENTS.md b/AGENTS.md
index 5a8a972..ee3f865 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,7 +82,7 @@ Neither `v1/__init__.py` nor the top-level `__init__.py` defines symbols — bot
Names come from the store's naming manifest. The binding holds no naming rule for a manifest type. `hatch run generate` runs three steps:
-1. **Hoist.** `python scripts/hoist_names.py` fetches the spec artifact pinned in `scripts/spec_artifact.py` (`0.7.0+oscal.1.2.3`, sha256-checked, cached in `tests/.corpus_cache/`), validates its `names.json` with `scripts/manifest.py` (manifest JSON Schema via `jsonschema-rs`, format and release, artifact-schema sha256, unique names, resolvable pointers), reads the complete OSCAL schema of the same artifact one time (the manifest check hashes the bytes that the hoist parses), and writes `build/codegen/oscal_complete_schema.json` (git-ignored). In that copy each manifest site is `definitions/` with a `$ref` at the site. A merge with different bodies, or a closed-enum value that its base datatype rejects, fails the run.
+1. **Hoist.** `python scripts/hoist_names.py` fetches the spec artifact pinned in `scripts/spec_artifact.py` (`0.8.0+oscal.1.2.3`, sha256-checked, cached in `tests/.corpus_cache/`), validates its `names.json` with `scripts/manifest.py` (manifest JSON Schema via `jsonschema-rs`, format and release, artifact-schema sha256, unique names, resolvable pointers), reads the complete OSCAL schema of the same artifact one time (the manifest check hashes the bytes that the hoist parses), and writes `build/codegen/oscal_complete_schema.json` (git-ignored). In that copy each manifest site is `definitions/` with a `$ref` at the site. A merge with different bodies, or a closed-enum value that its base datatype rejects, fails the run.
2. **Codegen.** `datamodel-codegen --input ./build/codegen/oscal_complete_schema.json --output ./build/codegen/models.py --base-class oscal_bindings.v1._base.OscalBaseModel --collapse-root-models ... --formatters black isort` (see DEVELOPING "Names reach codegen through the hoisted schema" for the flag choices). Each `object`, `document`, and `enum` class takes its name from its definition key. `--base-class` makes all 185 object models subclass `OscalBaseModel`; the two `RootModel`s (`OscalDocument`, `MappingCollectionMappings`) don't.
3. **Post-process.** `python scripts/postprocess_models.py --models ./build/codegen/models.py --output src/oscal_bindings/v1/models.py`. Phase 1 collapses scalar `RootModel`s to `Annotated` aliases and strips `pattern=` from non-string fields (`AwareDatetime`/`AnyUrl`/numeric/`EmailStr`). Then it adds the 13 union `TypeAlias`es (`CatalogGroup`, plain unions, so `isinstance` works) and writes each field that uses one as `Annotated[, Field(union_mode='left_to_right')]` (the variant properties are exclusive, so this picks the same variant as smart mode, faster, #43), the `MappingCollectionMappings` root model, and the `OscalDocument` root model. It discriminates `OscalDocument.root` on the root key of the input: each member is `Tag`-ged with its class name, the root key of each member is the manifest `body-field`, and `root_key_discriminator` (`v1/_base.py`) selects the one member to validate (an input with no known root key is one `oscal_document_type` error). It names each scalar alias from its definition key without the `oscal-complete-oscal-:` prefix. Three guards compare the result with the manifest and the artifact schema and report every offender: each manifest name is defined once in the form of its kind, each other name is a scalar alias named for a scalar definition of the schema, no name is defined twice, and no manifest name or scalar alias is bound by a module-level import. The manifest must record the sha256 of the `--schema` bytes. The completed module goes to `--output` through a temp file + `os.replace`; on a failure nothing is written to `--output`, so a failed `generate` leaves the committed `models.py` untouched. `generate` passes no `--schema`: an omitted `--schema` resolves at call time to `artifact_paths(ensure_spec_artifact()).schema`, and an explicit one (a candidate schema, or a small test schema) must still match `schema.sha256` of the manifest. `--models` falls back to its own default, `--output` defaults to `--models`; a missing path is a non-zero exit.
diff --git a/DEVELOPING.md b/DEVELOPING.md
index b61a484..d50c311 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -105,7 +105,7 @@ Every type name comes from the naming manifest, `names.json`, of the pinned spec
rule for a manifest type. `hatch run generate` runs three steps:
1. `scripts/hoist_names.py` writes `build/codegen/oscal_complete_schema.json` (git-ignored).
- 1. It fetches the spec artifact that `scripts/spec_artifact.py` pins (`0.7.0+oscal.1.2.3`, by sha256) through
+ 1. It fetches the spec artifact that `scripts/spec_artifact.py` pins (`0.8.0+oscal.1.2.3`, by sha256) through
`scripts/pinned_archive.py`.
2. `scripts/manifest.py` validates `names.json`: its JSON Schema from the same artifact (with `jsonschema-rs`), the
format version and OSCAL release, the sha256 of the artifact schema, unique names, and pointers that resolve.
diff --git a/scripts/spec_artifact.py b/scripts/spec_artifact.py
index 4807d34..1b671b9 100644
--- a/scripts/spec_artifact.py
+++ b/scripts/spec_artifact.py
@@ -21,9 +21,9 @@
if TYPE_CHECKING:
from collections.abc import Callable
-SPEC_ARTIFACT_VERSION = "0.7.0+oscal.1.2.3"
+SPEC_ARTIFACT_VERSION = "0.8.0+oscal.1.2.3"
SPEC_ARTIFACT_SHA256 = (
- "39f61f5c40200882106d9df6367d5aa5ccc6d604288741a8a70e93e119fa933e"
+ "3da20cc6127e033d82e47046435caefe2b3a7ad7554908da264e5f4fe7f48dda"
)
# The `+` of the version is written as %2B in the URL path.
_URL_VERSION = SPEC_ARTIFACT_VERSION.replace("+", "%2B")
diff --git a/tests/support/expected_failures.py b/tests/support/expected_failures.py
index a3ae0f0..aa3e362 100644
--- a/tests/support/expected_failures.py
+++ b/tests/support/expected_failures.py
@@ -18,4 +18,44 @@
# A round trip keeps six datetime fraction digits and drops the seventh.
"round-trip/seven-fraction-digits": f"{ISSUES}/19",
"yaml-round-trip/string-scalars": f"{ISSUES}/19",
+ # PRS-014: only failures of the selected nested-union branch.
+ "parse/closed-enum-out-of-set": f"{ISSUES}/69",
+ # ERR-012: read-error category for a file path that cannot be read.
+ "parse-file/directory": f"{ISSUES}/61",
+ # FAC-007: datetime bounds from assessment_period().
+ "assessment-period/mixed-offsets": f"{ISSUES}/58",
+ "assessment-period/equal-instant": f"{ISSUES}/58",
+ "assessment-period/seventh-fraction-digit": f"{ISSUES}/58",
+ # ELV-002: one element-type name for each manifest type.
+ "element-types/all": f"{ISSUES}/59",
+ # BMB-004, ERR-013: resource identifier from a key, builder-error category.
+ "build-resource/key": f"{ISSUES}/62",
+ "build-resource/key-with-title": f"{ISSUES}/62",
+ "build-resource/non-ascii-key": f"{ISSUES}/62",
+ "build-resource/key-and-identifier": f"{ISSUES}/62",
+ "build-resource/empty-key": f"{ISSUES}/62",
+ # FAC-001 to FAC-003, BMB-001 to BMB-003: the runner lacks these operations.
+ **dict.fromkeys(
+ (
+ "facade/catalog",
+ "facade/profile",
+ "facade/component-definition",
+ "facade/system-security-plan",
+ "facade/assessment-plan",
+ "facade/assessment-results",
+ "facade/plan-of-action-and-milestones",
+ "facade/mapping-collection",
+ "facade/missing-file",
+ "build-hash/default-algorithm",
+ "build-hash/algorithm-string",
+ "build-hash/off-list-algorithm",
+ "build-hash/invalid-algorithm",
+ "build-rlink/reference-only",
+ "build-rlink/media-type-and-hashes",
+ "build-resource/generated-identifier",
+ "build-resource/omitted-inputs",
+ "build-resource/invalid-document-id",
+ ),
+ f"{ISSUES}/63",
+ ),
}
diff --git a/tests/test_conformance.py b/tests/test_conformance.py
index 472e0f8..41924a4 100644
--- a/tests/test_conformance.py
+++ b/tests/test_conformance.py
@@ -211,6 +211,11 @@ def test_every_expected_failure_names_a_corpus_case() -> None:
assert stale == [], f"expected failures not in the pinned corpus: {stale}"
+@pytest.mark.xfail(
+ strict=True,
+ reason="read-error and builder-error are not mapped yet: "
+ "https://github.com/cairn-proofs/oscal-bindings-python/issues/61, /62",
+)
def test_every_category_is_mapped() -> None:
"""Each category in the corpus has a branch in ``category``."""
index = json.loads((corpus_root() / "cases.json").read_text("utf-8"))
diff --git a/tests/test_spec_artifact_script.py b/tests/test_spec_artifact_script.py
index db60529..e3c826b 100644
--- a/tests/test_spec_artifact_script.py
+++ b/tests/test_spec_artifact_script.py
@@ -28,9 +28,9 @@
def test_script_and_test_support_share_one_pin_and_one_cache() -> None:
assert spec_artifact.SPEC_ARTIFACT is pin.SPEC_ARTIFACT
- assert pin.SPEC_ARTIFACT_VERSION == "0.7.0+oscal.1.2.3"
+ assert pin.SPEC_ARTIFACT_VERSION == "0.8.0+oscal.1.2.3"
assert pin.SPEC_ARTIFACT_SHA256 == (
- "39f61f5c40200882106d9df6367d5aa5ccc6d604288741a8a70e93e119fa933e"
+ "3da20cc6127e033d82e47046435caefe2b3a7ad7554908da264e5f4fe7f48dda"
)
assert pin.CACHE_ROOT.resolve() == corpus.CACHE_ROOT.resolve()
assert REPO_ROOT.resolve() / "tests" / ".corpus_cache" == pin.CACHE_ROOT