From e6d7cfedc762dc7e24522bf724588f4cb2b14ae3 Mon Sep 17 00:00:00 2001 From: snkmcb Date: Wed, 23 Sep 2026 14:35:39 +0900 Subject: [PATCH 1/3] docs: record public Windows artifacts --- docs/roadmap/current.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/roadmap/current.md b/docs/roadmap/current.md index 26615f5..6260aa3 100644 --- a/docs/roadmap/current.md +++ b/docs/roadmap/current.md @@ -45,10 +45,11 @@ installed physicsCore + physicsJolt factory in standalone and usdview hosts. - Removed the repository-local physics libraries after the installed package path passed all 48 local Windows parity tests. +- Published the pinned Windows packages as public, immutable OCI artifacts and + verified both OCI and content digests from a fresh cache. ## 4. Remaining Phase 3 work -- Publish immutable OCI sources for the pinned Windows package artifacts. - Produce and publish equivalent Linux package artifacts. - Run the Stage Runner hosted Windows and Linux suites from fresh artifact caches and record the evidence. From 9906f240961db2d154d8f420b9bb058a849e7f7e Mon Sep 17 00:00:00 2001 From: snkmcb Date: Wed, 23 Sep 2026 14:59:44 +0900 Subject: [PATCH 2/3] docs: correct published Jolt ABI flags --- docs/architecture/DEPENDENCIES.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/architecture/DEPENDENCIES.md b/docs/architecture/DEPENDENCIES.md index cc6bad7..0a836a3 100644 --- a/docs/architecture/DEPENDENCIES.md +++ b/docs/architecture/DEPENDENCIES.md @@ -45,10 +45,10 @@ alternate target spelling; installed-package verification uses `Jolt::Jolt`. The verified Windows artifact is a Release, single-precision build with `DOUBLE_PRECISION=OFF`, `CROSS_PLATFORM_DETERMINISTIC=OFF`, and -`INTERPROCEDURAL_OPTIMIZATION=OFF`. Its enabled x86 features are SSE4.1, -SSE4.2, AVX, AVX2, LZCNT, TZCNT, F16C, and FMADD; AVX512 is disabled. A Jolt -artifact with different ABI-affecting definitions must not be mixed into the -same process. +`INTERPROCEDURAL_OPTIMIZATION=OFF`. Its imported target exports no optional x86 +instruction-set definitions; compatible consumer builds disable SSE4.1, SSE4.2, +AVX, AVX2, AVX512, LZCNT, TZCNT, F16C, and FMADD. A Jolt artifact with different +ABI-affecting definitions must not be mixed into the same process. The installed `physicsJolt` package rechecks Jolt 5.5.0 and the exact exported ABI compile-definition set before importing its static target. A downstream From 6b29a66bf5e1ba6fc3f659c45a0cb839ba616508 Mon Sep 17 00:00:00 2001 From: snkmcb Date: Wed, 23 Sep 2026 19:07:56 +0900 Subject: [PATCH 3/3] docs: define physics artifact release schema --- docs/README.md | 4 +- docs/architecture/RELEASE_SCHEMA.md | 96 +++++++++++++++++++++++++++++ docs/contributing/documentation.md | 2 + docs/roadmap/current.md | 4 ++ 4 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/RELEASE_SCHEMA.md diff --git a/docs/README.md b/docs/README.md index 969e252..76cc5d2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,7 @@ claim implementation status. | Category | Answers | Start here | | --- | --- | --- | -| [architecture/](architecture/) | How the workspace is structured: identities, dependency directions, external dependencies, and installed packages. | [WORKSPACE.md](architecture/WORKSPACE.md) · [DEPENDENCIES.md](architecture/DEPENDENCIES.md) · [PACKAGE_CONTRACT.md](architecture/PACKAGE_CONTRACT.md) | +| [architecture/](architecture/) | How the workspace is structured: identities, dependency directions, external dependencies, installed packages, and release schema. | [WORKSPACE.md](architecture/WORKSPACE.md) · [DEPENDENCIES.md](architecture/DEPENDENCIES.md) · [PACKAGE_CONTRACT.md](architecture/PACKAGE_CONTRACT.md) · [RELEASE_SCHEMA.md](architecture/RELEASE_SCHEMA.md) | | [design/](design/) | What the runtime contracts mean and why the boundaries exist. | [DESIGN_POLICY.md](design/DESIGN_POLICY.md) · [RIGID_BODY_CONTRACT.md](design/RIGID_BODY_CONTRACT.md) · [USD_BRIDGE_CONTRACT.md](design/USD_BRIDGE_CONTRACT.md) · [SECONDARY_MOTION_CONTRACT.md](design/SECONDARY_MOTION_CONTRACT.md) | | [reference/](reference/) | Facts about the current tree, extraction input, and implemented capabilities. | [CAPABILITY_MATRIX.md](reference/CAPABILITY_MATRIX.md) · [EXTRACTION_BASELINE.md](reference/EXTRACTION_BASELINE.md) | | [roadmap/](roadmap/) | What is planned next, what is incomplete, and which phase owns it. | [README.md](roadmap/README.md) · [current.md](roadmap/current.md) | @@ -56,5 +56,7 @@ actual release exist. `reports/` begins with the Phase 0 scaffold verification. [architecture/DEPENDENCIES.md](architecture/DEPENDENCIES.md). - Package names and consumer guarantees belong only in [architecture/PACKAGE_CONTRACT.md](architecture/PACKAGE_CONTRACT.md). +- Release units, registry identities, and promotion gates belong in + [architecture/RELEASE_SCHEMA.md](architecture/RELEASE_SCHEMA.md). - The full maintenance rules are in [contributing/documentation.md](contributing/documentation.md). diff --git a/docs/architecture/RELEASE_SCHEMA.md b/docs/architecture/RELEASE_SCHEMA.md new file mode 100644 index 0000000..7452b1f --- /dev/null +++ b/docs/architecture/RELEASE_SCHEMA.md @@ -0,0 +1,96 @@ +# Release schema + +> **Status: proposed, 2026-09-23.** This defines the intended versioned +> release contract; it does not claim that a tag, release workflow, or GitHub +> release exists. The public Windows artifacts published during Phase 3 are +> consumer-validation inputs, not a complete `v0.1.0` release. + +## 1. Release unit and scope + +One repository version in `VERSION` applies to every released library. The +initial release set is `physicsCore` and the Jolt-enabled `physicsJolt`, for +`cy2026` / `usd` on Windows x86_64 and Linux x86_64. A new library or target +joins the set only after its clean-prefix and downstream-consumer checks pass. +macOS and a no-Jolt stub are not release targets for this first set. + +The distributable unit is an individual OpenStrata library artifact, not a +workspace source checkout or an umbrella package. Its installed CMake target +and dependency contract remain governed by [PACKAGE_CONTRACT.md](PACKAGE_CONTRACT.md). +`physicsJolt` must record and enforce the Jolt version and ABI-affecting build +definitions used for that target; a matching library artifact alone does not +replace its external Jolt SDK dependency. + +## 2. Registry identity and consumer pins + +All released libraries use the existing public OCI repository +`ghcr.io/animu-sphere/usd-physics-plugins`. A discoverable tag has the shape +`--`, but a consumer must pin two digests obtained +from the actual published artifact: + +```yaml +requires: + libraries: + - id: physicsCore + version: ">=0.1,<0.2" + artifact: + targets: + cy2026-windows-x86_64-py313-usd: + digest: sha256: + source: oci://ghcr.io/animu-sphere/usd-physics-plugins@sha256: + - id: physicsJolt + version: ">=0.1,<0.2" + artifact: + targets: + cy2026-windows-x86_64-py313-usd: + digest: sha256: + source: oci://ghcr.io/animu-sphere/usd-physics-plugins@sha256: +``` + +The `digest` is the OpenStrata archive content digest; the digest in `source` +identifies its OCI manifest. They are not interchangeable. Tags are discovery +labels only and must never replace digest pins. Publishing a target again may +change its OCI digest, so the consumer pin table is generated from successful +push results, not from a planned tag or locally packaged archive alone. +Because `physicsJolt` declares `physicsCore`, a consumer selecting Jolt must +include both exact pins in the selected OpenStrata library closure. + +The pin table must contain exactly one entry per released library and target, +with version, target, content digest, and OCI source. It ships as both a +machine-readable release asset and a copyable consumer example in the release +notes. A missing library or target fails the release rather than producing a +partial table. + +## 3. Promotion gates + +The eventual release workflow has two modes: + +1. A manual dry run builds, tests, packages, and stages the complete release + set, but neither pushes to GHCR nor creates a GitHub release. Its pin table + includes local content digests and explicitly omits `source`. +2. A `vX.Y.Z` tag is accepted only when it matches `VERSION` and has finalized + release notes. It runs the same verification, then publishes each library + and target, generates the digest pin table, checksums the release files, and + creates a draft GitHub release for human review. + +The build matrix must mirror the corresponding source-CI runtime digests, +OpenStrata version, OS/architecture, Python ABI, and external Jolt revision. +Each target must pass root tests, isolated library tests, package creation, +clean-prefix installed-consumer tests, and a downstream Stage Runner consumer +check before promotion. Windows validation must include a compiler-compatible +link test against the published binaries; source-only tests cannot establish +that ABI compatibility. + +Publishing credentials belong only to the tag-only publish job. PR and dry-run +jobs stay read-only. Release artifacts are retained with checksums and the +exact pins; publishing does not by itself mark a version released until the +draft is reviewed and published. + +## 4. Current boundary + +The existing public Windows `physicsCore` and `physicsJolt` OCI artifacts have +been pulled and verified from a fresh cache for the Phase 3 migration. They +remain valid exact-digest inputs for that consumer, but do not imply Linux +availability or a formal versioned release. The first release workflow should +be implemented and dry-run before any `v0.1.0` tag is pushed. Linux artifacts, +cross-repository hosted consumer evidence, and a finalized release note are +still required. diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 04267e5..acb6057 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -56,6 +56,8 @@ Open questions use a document-specific prefix and a never-reused number: [DEPENDENCIES.md](../architecture/DEPENDENCIES.md). - Installed package promises: [PACKAGE_CONTRACT.md](../architecture/PACKAGE_CONTRACT.md). +- Release identity and promotion gates: + [RELEASE_SCHEMA.md](../architecture/RELEASE_SCHEMA.md). - What is implemented: [CAPABILITY_MATRIX.md](../reference/CAPABILITY_MATRIX.md). diff --git a/docs/roadmap/current.md b/docs/roadmap/current.md index 6260aa3..893a277 100644 --- a/docs/roadmap/current.md +++ b/docs/roadmap/current.md @@ -53,6 +53,10 @@ installed physicsCore + physicsJolt - Produce and publish equivalent Linux package artifacts. - Run the Stage Runner hosted Windows and Linux suites from fresh artifact caches and record the evidence. +- Implement and dry-run the versioned release workflow against the + [release schema](../architecture/RELEASE_SCHEMA.md) before creating a tag; + the currently published Windows artifacts are Phase 3 inputs, not a full + release. ## 5. Phase 3 completion criteria