Merge pull request #90 from AbdelStark/vendoring/stwo

vendoring: vendor and pin Stwo under third_party/stwo

Author: AbdelStark

Cargo.lock

@@ -12,6 +12,11 @@
 [workspace]
 resolver = "2"
 members = ["crates/*"]
+# Vendored proving substrate (RFC-0015) is its own upstream workspace; it is not
+# a member of ours. First-party crates depend on individual vendored crates by
+# path (the only permitted source, INV-RFC0015-01); the vendored workspace keeps
+# its own manifest/lockfile and is excluded here so cargo does not absorb it.
+exclude = ["third_party/stwo", "third_party/stwo-circuits"]
 
 [workspace.package]
 version = "0.1.0"
@@ -36,6 +41,10 @@ pwm-air = { path = "crates/pwm-air", version = "0.1.0" }
 pwm-export = { path = "crates/pwm-export", version = "0.1.0" }
 pwm-prover = { path = "crates/pwm-prover", version = "0.1.0" }
 pwm-verifier = { path = "crates/pwm-verifier", version = "0.1.0" }
+# Vendored proving substrate (RFC-0015). Path dependencies only — never a
+# crates.io or git source for a Stwo package (INV-RFC0015-01). The vendored tree
+# is pinned at stwo v2.2.0 (third_party/stwo/REVISION).
+stwo = { path = "third_party/stwo/crates/stwo", version = "2.2.0" }
 # Test-only third-party dependencies (used by pwm-testkit and pwm-core dev-deps).
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

Cargo.toml

@@ -14,6 +14,10 @@ pwm-core = { workspace = true }
 pwm-air = { workspace = true }
 pwm-circuits = { workspace = true }
 pwm-export = { workspace = true }
+# Vendored Stwo prover (RFC-0015), referenced by path only. This is the first
+# in-tree consumer that proves third_party/stwo builds as a path dependency; the
+# prover drives the Stwo commit/challenge/proof flow.
+stwo = { workspace = true }
 
 [lints]
 workspace = true

crates/pwm-prover/Cargo.toml

@@ -20,3 +20,6 @@ use pwm_air as _;
 use pwm_circuits as _;
 use pwm_core as _;
 use pwm_export as _;
+// Vendored proving substrate (third_party/stwo, RFC-0015). Linked here to prove
+// the path-dependency wiring builds; the prover flow uses it from #62 onward.
+use stwo as _;

crates/pwm-prover/src/lib.rs

@@ -12,8 +12,10 @@
 allow = [
     "Apache-2.0",
     "MIT",
+    "BSD-2-Clause",
     "BSD-3-Clause",
     "Unicode-3.0",
+    "Zlib",
 ]
 confidence-threshold = 0.9
 # The allow list is forward-looking (no external deps exist on the skeleton yet);

deny.toml

@@ -168,14 +168,14 @@ third_party/
     PATCHES/
       0001-<slug>.patch       # one file per local modification, applied in order
       0001-<slug>.md          # rationale, audit note, upstream-PR/issue link or "none"
-    src/...                   # vendored source tree (workspace member crates)
+    crates/...                # vendored source tree, upstream layout preserved verbatim
   stwo-circuits/
     REVISION
     LICENSE
     NOTICE
     UPSTREAM.md
     PATCHES/
-    src/...
+    crates/...
 ```
 
 `third_party/<comp>/REVISION` is the single source of truth for the pin. Schema
@@ -210,10 +210,12 @@ path dependency into the vendored tree.
 
 ```toml
 # crates/pwm-air/Cargo.toml — REQUIRED form
+# (The vendored tree preserves the upstream `crates/` layout verbatim, so the
+#  path is `third_party/stwo/crates/<dir>`; see third_party/stwo/UPSTREAM.md.)
 [dependencies]
-stwo                       = { path = "../../third_party/stwo/src/stwo" }
-stwo-constraint-framework  = { path = "../../third_party/stwo/src/stwo-constraint-framework" }
-stwo-air-utils             = { path = "../../third_party/stwo/src/stwo-air-utils" }
+stwo                       = { path = "../../third_party/stwo/crates/stwo" }
+stwo-constraint-framework  = { path = "../../third_party/stwo/crates/constraint-framework" }
+stwo-air-utils             = { path = "../../third_party/stwo/crates/air-utils" }
 
 # FORBIDDEN forms (CI gate rejects either):
 # stwo = "2.2.0"

docs/rfcs/RFC-0015-third-party-vendoring-and-pinning.md

@@ -0,0 +1,39 @@
+# Third-party dependency and license inventory
+
+The authoritative inventory of vendored components and their license surface,
+per [RFC-0015](../docs/rfcs/RFC-0015-third-party-vendoring-and-pinning.md). The
+`cargo deny check licenses` gate ([`deny.toml`](../deny.toml)) enforces the
+allowed-license set against the resolved dependency graph on every PR.
+
+## Vendored components
+
+| Component | Path | Pin | License | REVISION |
+| --- | --- | --- | --- | --- |
+| Stwo | `third_party/stwo` | `v2.2.0` (`289c20de`) | Apache-2.0 | [`stwo/REVISION`](stwo/REVISION) |
+| stwo-circuits | `third_party/stwo-circuits` | `v0.1.0` (`b0db13e4`) | Apache-2.0 | pending (#25) |
+
+Each vendored component is pinned by commit, carries its upstream `LICENSE`
+verbatim and a recorded `NOTICE`, and is referenced by path only (INV-RFC0015-01:
+no crates.io/git source for a substrate package).
+
+## License surface of the resolved graph (Stwo vendored)
+
+Licenses present in the transitive dependency tree once `stwo` is wired in. Every
+crate resolves to at least one allowed license (dual-licensed crates list every
+option; the allowed alternative satisfies the gate).
+
+| SPDX license | Allowed | Notes |
+| --- | --- | --- |
+| Apache-2.0 | yes | project license; most of the tree |
+| MIT | yes | most of the tree (dual with Apache-2.0) |
+| BSD-2-Clause | yes | `arrayref` (single), `zerocopy` (dual) |
+| BSD-3-Clause | yes | `subtle` |
+| Unicode-3.0 | yes | `unicode-ident` (dual) |
+| Zlib | yes | `foldhash` (single), `bytemuck` (dual) |
+| Apache-2.0 WITH LLVM-exception | via Apache-2.0 | `blake3`, `wasi` (dual with Apache-2.0) |
+| CC0-1.0 / MIT-0 / Unlicense | via alternative | `blake3`, `constant_time_eq`, `memchr` — each dual with an allowed license |
+
+The allow-list lives in [`deny.toml`](../deny.toml). Duplicate dependency
+versions (e.g. `itertools` 0.10/0.12, `hashbrown` 0.14/0.17, `syn` 1/2) are
+permitted (`bans.multiple-versions = "allow"`) because they originate in the
+pinned upstream tree; tightening is tracked by the vendoring-audit work (#26).

third_party/INVENTORY.md

@@ -12,13 +12,17 @@ vendoring, modification, and re-audit policy is governed by
 | `stwo/` | github.com/starkware-libs/stwo | Apache-2.0 | Workspace v2.2.0 — Circle-STARK prover/verifier, M31 field module, FRI + PCS, Fiat-Shamir channels, LogUp. |
 | `stwo-circuits/` | github.com/starkware-libs/stwo-circuits | Apache-2.0 | v0.1.0 (edition 2024) — the low-level scalar gate set. |
 
+The authoritative TCB / license inventory is [`INVENTORY.md`](INVENTORY.md).
+
 ## Status
 
-This is the workspace skeleton (issue #23). The actual upstream code is **not**
-vendored yet; that is the work of issues #24 (`stwo`) and #25 (`stwo-circuits`).
-Each subtree carries a `REVISION` file recording the exact pinned commit. Until
-the revisions are frozen during the `v0.1 — Foundations` milestone, both files
-contain the placeholder string `pending-rfc-0015`.
+- **`stwo/`** — vendored (#24). Pristine at `v2.2.0`
+  (`289c20de80b7c7f508de9c46151fb81dae404154`); see [`stwo/REVISION`](stwo/REVISION)
+  and [`stwo/UPSTREAM.md`](stwo/UPSTREAM.md). First-party crates depend on it by
+  path; the tree is its own workspace and is `exclude`d from the first-party
+  workspace.
+- **`stwo-circuits/`** — not vendored yet (#25); `REVISION` holds the placeholder
+  `pending-rfc-0015`.
 
 Vendored files retain their upstream license headers unmodified; the first-party
 SPDX header lint excludes `third_party/`