snkmcb · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git 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/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

diff --git a/docs/architecture/RELEASE_SCHEMA.md 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
+`<library>-<version>-<target>`, 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:<archive-content-digest>
+            source: oci://ghcr.io/animu-sphere/usd-physics-plugins@sha256:<oci-manifest-digest>
+    - id: physicsJolt
+      version: ">=0.1,<0.2"
+      artifact:
+        targets:
+          cy2026-windows-x86_64-py313-usd:
+            digest: sha256:<jolt-archive-content-digest>
+            source: oci://ghcr.io/animu-sphere/usd-physics-plugins@sha256:<jolt-oci-manifest-digest>
+```
+
+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
@@ -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
@@ -45,13 +45,18 @@ 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.
+- 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