fora-protocol 1.0.3__tar.gz

fora_protocol-1.0.3/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 FORA-Protocol contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fora_protocol-1.0.3/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: fora-protocol
+Version: 1.0.3
+Summary: Generated types export for Python: Pydantic v2 models (wire.models, extending wire.base.WireModel) + registered vocabulary constants (vocab.*), generated from the proto via JSON Schema.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://fora-protocol.org
+Project-URL: Source, https://github.com/FORA-Protocol/protocol
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+# Generated Python types export
+
+Generated from [`proto/`](../../proto) via JSON Schema. **Do not edit by hand** —
+regenerate with `scripts/gen-sdk-types.sh` and commit the result (CI drift-gates it).
+
+A **types export**, not a full SDK: Pydantic models + registered vocabulary constants.
+Transport (Connect), request signing (RFC 9421), and key management are a separate,
+hand-written SDK layer.
+
+Contents:
+- `wire/base.py` — **`WireModel`**, the single base class every model extends (the one
+  seam: SDK-wide config + your override point; neutral name so a protocol rename never
+  touches consumer imports). **Hand-written, not regenerated.**
+- `wire/models.py` — Pydantic v2 models for every message (`License`, `Pricing`,
+  `LicenseTerm`, `Offer`, …), all extending `WireModel`. They carry **shape + per-field
+  validation**: enums (named from the proto descriptor, `*_UNSPECIFIED` dropped),
+  string patterns, length/item bounds. Nested messages reference the same model
+  (`LicenseTerm.license` is a `License`), so the whole tree hydrates as typed models.
+  **Cross-field rules are NOT here** — enforced server-side by the Exchange/Broker.
+- `vocab/` — registered vocabulary constants per axis (`pricingunits`, …) with
+  `is_registered()`, plus the accepted aliases authored beside the tokens (`ALIASES`,
+  `canonical()` — an exact lookup; the SDK folds case before it looks up).
+
+```python
+from wire.models import LicenseTerm, License
+from wire.base import WireModel          # subclass this to customize ALL models at once
+
+term = LicenseTerm.model_validate(incoming_json)   # raises on shape/per-field violations
+assert isinstance(term.license, License)           # full nested hierarchy, typed
+```
+
+Install (from this directory): `pip install .`
+
+## Import names and PyPI
+
+The distribution is published on PyPI as `fora-protocol`. Its import packages are the
+generic top-level names `wire` and `vocab`, so it can collide with any other distribution
+that owns either name; install it into an environment that does not. This is a deliberate
+tradeoff: a rename to a namespaced package would break every consumer that installs from
+this repository by git ref, so the names stay as they are.
+
+```sh
+pip install fora-protocol
+```

fora_protocol-1.0.3/README.md

@@ -0,0 +1,44 @@
+# Generated Python types export
+
+Generated from [`proto/`](../../proto) via JSON Schema. **Do not edit by hand** —
+regenerate with `scripts/gen-sdk-types.sh` and commit the result (CI drift-gates it).
+
+A **types export**, not a full SDK: Pydantic models + registered vocabulary constants.
+Transport (Connect), request signing (RFC 9421), and key management are a separate,
+hand-written SDK layer.
+
+Contents:
+- `wire/base.py` — **`WireModel`**, the single base class every model extends (the one
+  seam: SDK-wide config + your override point; neutral name so a protocol rename never
+  touches consumer imports). **Hand-written, not regenerated.**
+- `wire/models.py` — Pydantic v2 models for every message (`License`, `Pricing`,
+  `LicenseTerm`, `Offer`, …), all extending `WireModel`. They carry **shape + per-field
+  validation**: enums (named from the proto descriptor, `*_UNSPECIFIED` dropped),
+  string patterns, length/item bounds. Nested messages reference the same model
+  (`LicenseTerm.license` is a `License`), so the whole tree hydrates as typed models.
+  **Cross-field rules are NOT here** — enforced server-side by the Exchange/Broker.
+- `vocab/` — registered vocabulary constants per axis (`pricingunits`, …) with
+  `is_registered()`, plus the accepted aliases authored beside the tokens (`ALIASES`,
+  `canonical()` — an exact lookup; the SDK folds case before it looks up).
+
+```python
+from wire.models import LicenseTerm, License
+from wire.base import WireModel          # subclass this to customize ALL models at once
+
+term = LicenseTerm.model_validate(incoming_json)   # raises on shape/per-field violations
+assert isinstance(term.license, License)           # full nested hierarchy, typed
+```
+
+Install (from this directory): `pip install .`
+
+## Import names and PyPI
+
+The distribution is published on PyPI as `fora-protocol`. Its import packages are the
+generic top-level names `wire` and `vocab`, so it can collide with any other distribution
+that owns either name; install it into an environment that does not. This is a deliberate
+tradeoff: a rename to a namespaced package would break every consumer that installs from
+this repository by git ref, so the names stay as they are.
+
+```sh
+pip install fora-protocol
+```

fora_protocol-1.0.3/fora_protocol.egg-info/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: fora-protocol
+Version: 1.0.3
+Summary: Generated types export for Python: Pydantic v2 models (wire.models, extending wire.base.WireModel) + registered vocabulary constants (vocab.*), generated from the proto via JSON Schema.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://fora-protocol.org
+Project-URL: Source, https://github.com/FORA-Protocol/protocol
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+# Generated Python types export
+
+Generated from [`proto/`](../../proto) via JSON Schema. **Do not edit by hand** —
+regenerate with `scripts/gen-sdk-types.sh` and commit the result (CI drift-gates it).
+
+A **types export**, not a full SDK: Pydantic models + registered vocabulary constants.
+Transport (Connect), request signing (RFC 9421), and key management are a separate,
+hand-written SDK layer.
+
+Contents:
+- `wire/base.py` — **`WireModel`**, the single base class every model extends (the one
+  seam: SDK-wide config + your override point; neutral name so a protocol rename never
+  touches consumer imports). **Hand-written, not regenerated.**
+- `wire/models.py` — Pydantic v2 models for every message (`License`, `Pricing`,
+  `LicenseTerm`, `Offer`, …), all extending `WireModel`. They carry **shape + per-field
+  validation**: enums (named from the proto descriptor, `*_UNSPECIFIED` dropped),
+  string patterns, length/item bounds. Nested messages reference the same model
+  (`LicenseTerm.license` is a `License`), so the whole tree hydrates as typed models.
+  **Cross-field rules are NOT here** — enforced server-side by the Exchange/Broker.
+- `vocab/` — registered vocabulary constants per axis (`pricingunits`, …) with
+  `is_registered()`, plus the accepted aliases authored beside the tokens (`ALIASES`,
+  `canonical()` — an exact lookup; the SDK folds case before it looks up).
+
+```python
+from wire.models import LicenseTerm, License
+from wire.base import WireModel          # subclass this to customize ALL models at once
+
+term = LicenseTerm.model_validate(incoming_json)   # raises on shape/per-field violations
+assert isinstance(term.license, License)           # full nested hierarchy, typed
+```
+
+Install (from this directory): `pip install .`
+
+## Import names and PyPI
+
+The distribution is published on PyPI as `fora-protocol`. Its import packages are the
+generic top-level names `wire` and `vocab`, so it can collide with any other distribution
+that owns either name; install it into an environment that does not. This is a deliberate
+tradeoff: a rename to a namespaced package would break every consumer that installs from
+this repository by git ref, so the names stay as they are.
+
+```sh
+pip install fora-protocol
+```

fora_protocol-1.0.3/fora_protocol.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+LICENSE
+README.md
+pyproject.toml
+fora_protocol.egg-info/PKG-INFO
+fora_protocol.egg-info/SOURCES.txt
+fora_protocol.egg-info/dependency_links.txt
+fora_protocol.egg-info/requires.txt
+fora_protocol.egg-info/top_level.txt
+tests/test_comment_first_paragraph.py
+tests/test_forward_compat.py
+tests/test_money_pattern.py
+tests/test_money_roundtrip.py
+tests/test_numeric_wire_forms.py
+tests/test_parity.py
+tests/test_snake_fields.py
+tests/test_unique_subclass.py
+tests/test_wire_policy.py
+vocab/functiontokens.py
+vocab/geographytokens.py
+vocab/pricingunits.py
+vocab/py.typed
+vocab/quotametrics.py
+vocab/usertypes.py
+wire/base.py
+wire/models.py
+wire/names.py
+wire/py.typed
+wire/unique.py

fora_protocol-1.0.3/fora_protocol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fora_protocol-1.0.3/fora_protocol.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=2.0

fora_protocol-1.0.3/fora_protocol.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+vocab
+wire

fora_protocol-1.0.3/pyproject.toml

@@ -0,0 +1,38 @@
+# Packaging for the generated FORA Python types export (mirrors gen/ts/package.json).
+# wire/models.py and vocab/* are generated from proto/ by scripts/gen-sdk-types.sh — do
+# not edit them by hand. Only this file, README.md, and the hand-written wire/base.py
+# seam are authored.
+[build-system]
+requires = ["setuptools>=77"] # license-files (PEP 639)
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fora-protocol"
+version = "1.0.3"
+description = "Generated types export for Python: Pydantic v2 models (wire.models, extending wire.base.WireModel) + registered vocabulary constants (vocab.*), generated from the proto via JSON Schema."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+# Pydantic for the message models; vocabulary constants are pure string literals.
+dependencies = [
+  "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://fora-protocol.org"
+Source = "https://github.com/FORA-Protocol/protocol"
+
+[tool.setuptools.packages.find]
+where = ["."]
+# PEP 420 namespace packages. Pydantic models + base at wire.* (neutral name, no
+# protocol coupling); vocabulary constants at vocab.pricingunits (etc.).
+namespaces = true
+include = ["wire*", "vocab*"]
+
+# The inline-types marker, one per namespace package (a namespace package has no
+# __init__.py to carry it), in the wheel and the sdist.
+[tool.setuptools.package-data]
+wire = ["py.typed"]
+vocab = ["py.typed"]
+

fora_protocol-1.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fora_protocol-1.0.3/tests/test_comment_first_paragraph.py

@@ -0,0 +1,142 @@
+"""A proto comment's FIRST paragraph must survive into the generated clients.
+
+protoschema splits a multi-paragraph proto comment: paragraph one becomes the JSON
+Schema `title`, the remainder becomes `description`. The merge step used to remove every
+key named `title` from the intermediate document, which cost two different things:
+
+  * the head of every multi-paragraph comment. `Offer.signature` reached Pydantic and Zod
+    describing the canonical-signing rules without ever saying the field IS the signature
+    or that it is required. Go was unaffected — fora.pb.go carries the whole comment — so
+    the loss was visible only in these two clients.
+  * three whole FIELDS. `Offer.title`, `ResourceEntry.title` and `UsageAsset.title` are
+    proto fields whose NAME is `title`, so a blanket key-strip deleted them from
+    `properties` outright. No corpus case populates any of them, so the canonical
+    round-trip gate saw nothing to lose and stayed green.
+
+merge_schema.assert_no_surviving_titles is the structural guard: it fails the build when
+a title reaches the write, so a site the resolver does not reach can no longer ship. This
+file is the behavioral half, over the COMMITTED output a consumer actually installs.
+Titles that merely restate the field's own enum or message type carry nothing the comment
+said and are still dropped; that is asserted too, so a fix cannot over-correct into noise.
+
+Run:  PYTHONPATH=gen/python python3 -m pytest gen/python/tests/test_comment_first_paragraph.py -q
+"""
+
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from wire import models  # noqa: E402
+
+# gen/python/tests -> gen/python -> gen -> <repo root>
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_ZOD = _REPO_ROOT / "gen" / "ts" / "wire" / "schemas.ts"
+
+#: Fields whose NAME is `title`. Present in the proto, and absent from both clients until
+#: the strip was replaced. One entry per message that declares one.
+TITLE_FIELDS = ("Offer", "ResourceEntry", "UsageAsset")
+
+#: (model, field, the comment head that must open the generated description). Each is a
+#: field whose proto comment carries a blank line, so protoschema routed its first
+#: paragraph into `title`. Spot checks, not the whole set — the build-time guard owns
+#: completeness; these name the cases a reader can check against the .proto by eye.
+FIRST_PARAGRAPH_HEADS = (
+    ("Offer", "signature", "REQUIRED. Hex-encoded detached Ed25519 signature over the canonical"),
+    ("Requester", "scopes", "Entitlement scopes. Declare what the requester can access."),
+    ("License", "uri", "Canonical identity of the license document (RFC 3986)."),
+    ("ResourceQuery", "supported_profiles", "Domain extension profiles the caller understands."),
+    ("Pricing", "unit", 'Metering basis — the "per what" of PER_UNIT pricing.'),
+)
+
+#: (model, field, the type-derived title that must NOT appear). protoschema fills `title`
+#: in from the field's enum type when the comment is a single paragraph, so prepending it
+#: would inject the type's name into a field whose comment lost nothing.
+TYPE_DERIVED_TITLES = (
+    ("DisputeRequest", "reason", "Dispute Reason"),
+    ("Pricing", "model", "Pricing Model"),
+    ("WellKnownManifest", "role", "Role"),
+    ("ResourceIdentity", "c2pa_status", "C2PA Status"),
+)
+
+
+def _description(model_name: str, field_name: str) -> str:
+    cls = getattr(models, model_name)
+    field = cls.model_fields[field_name]
+    assert field.description is not None, f"{model_name}.{field_name} carries no description"
+    return field.description
+
+
+def _collapsed(text: str) -> str:
+    """Whitespace-insensitive form. A proto comment wraps across `//` lines, so the
+    generated description carries the author's line breaks; only the words are the rule."""
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _zod_schema_of(source: str, message: str) -> str:
+    """One generated Zod schema. json-schema-to-zod emits each on a single line."""
+    marker = f"export const {message}Schema = "
+    start = source.index(marker)
+    return source[start : source.index("\n", start)]
+
+
+def test_fields_named_title_reach_the_generated_models():
+    missing = [m for m in TITLE_FIELDS if "title" not in getattr(models, m).model_fields]
+    assert not missing, (
+        "proto field `title` is absent from the generated Pydantic models "
+        f"({missing}) — a key-strip is deleting the field, not a JSON-Schema keyword"
+    )
+
+
+def test_fields_named_title_reach_the_generated_zod_schemas():
+    source = _ZOD.read_text(encoding="utf-8")
+    missing = [m for m in TITLE_FIELDS if '"title"' not in _zod_schema_of(source, m)]
+    assert not missing, (
+        "proto field `title` is absent from the generated Zod schemas "
+        f"({missing}) — a key-strip is deleting the field, not a JSON-Schema keyword"
+    )
+
+
+def test_first_comment_paragraph_opens_the_generated_description():
+    for model_name, field_name, head in FIRST_PARAGRAPH_HEADS:
+        description = _collapsed(_description(model_name, field_name))
+        assert description.startswith(_collapsed(head)), (
+            f"{model_name}.{field_name} description does not open with its comment's "
+            f"first paragraph — got {description[:80]!r}"
+        )
+
+
+def test_type_derived_titles_are_not_prepended():
+    for model_name, field_name, type_title in TYPE_DERIVED_TITLES:
+        description = _description(model_name, field_name)
+        # The RAW description, and the paragraph break, are both load-bearing here: a
+        # carried title is prepended as its own paragraph, so that is the shape to refuse.
+        # A collapsed comparison would fire on WellKnownManifest.role, whose genuine
+        # comment legitimately opens with the word "Role".
+        assert not description.startswith(f"{type_title}\n\n"), (
+            f"{model_name}.{field_name} description opens with its own TYPE name "
+            f"({type_title!r}) as a carried paragraph — a title protoschema derived from "
+            "the type restates the type and must stay dropped"
+        )
+        assert description.strip() != type_title, (
+            f"{model_name}.{field_name} description IS its own type name ({type_title!r})"
+        )
+
+
+def test_message_comment_first_paragraph_reaches_the_zod_schemas():
+    """The message-level half, which only the Zod export renders.
+
+    datamodel-code-generator emits no class docstring, so a message's description is
+    invisible in models.py; json-schema-to-zod emits it as the schema's own .describe(),
+    where the loss was observable.
+    """
+    source = _ZOD.read_text(encoding="utf-8")
+    for head in (
+        "Offer — A single resource offer from an Exchange.",
+        "LicenseTerm — Universal licensing unit.",
+        "Requester — Universal identity for any FORA client.",
+    ):
+        assert head in source, (
+            f"message comment head {head!r} is missing from the generated Zod schemas"
+        )

fora_protocol-1.0.3/tests/test_forward_compat.py

@@ -0,0 +1,59 @@
+"""Direct behavioral regression for wire forward-compatibility.
+
+Core invariant: an UNKNOWN top-level field (a field a newer protocol version
+adds that this older client has never seen) MUST be ACCEPTED and DROPPED — not
+rejected, not retained. This is the whole point of WireModel's
+`model_config = ConfigDict(extra="ignore")`: an older SDK keeps parsing a newer
+message instead of failing closed.
+
+This exercises the REAL generated models (wire.models) through their public
+parse surface (model_validate on proto-JSON dicts, routed through
+wire.base.WireModel). No corpus, no source scanning — behavior only.
+
+Run:  PYTHONPATH=gen/python python3 -m pytest gen/python/tests/test_forward_compat.py -q
+
+It FAILS today: every generated model carries its own
+`model_config = ConfigDict(extra='forbid')`, which SHADOWS the WireModel
+extra='ignore' seam in Pydantic v2, so the unknown field raises ValidationError
+instead of being dropped.
+"""
+import pytest
+from pydantic import ValidationError
+
+import wire.models as models
+
+# A key no protocol version defines — stands in for "a field a newer version added".
+UNKNOWN_KEY = "__unknown_future_field__"
+
+# Representative models with a minimally-valid proto-JSON body (only what the
+# model REQUIRES) so the sole variable under test is the extra unknown field.
+# (case_id, ModelClass, base_instance)
+DROP_CASES = [
+    ("Cost", models.Cost, {"amount": "19.99"}),
+    ("Delegation", models.Delegation, {"principal_id": "user@acme.com"}),
+    ("Pricing", models.Pricing, {"model": models.PricingModel.PRICING_MODEL_FREE.value}),
+]
+
+
+@pytest.mark.parametrize(
+    "cls,base",
+    [(cls, base) for _, cls, base in DROP_CASES],
+    ids=[cid for cid, *_ in DROP_CASES],
+)
+def test_unknown_top_level_field_accepted_and_dropped(cls, base):
+    instance = {**base, UNKNOWN_KEY: "a value from the future"}
+
+    # MUST NOT raise: an unknown top-level field is accepted (forward-compat).
+    parsed = cls.model_validate(instance)
+
+    # MUST be dropped, not retained: it is absent from the model and its dump.
+    assert not hasattr(parsed, UNKNOWN_KEY)
+    assert UNKNOWN_KEY not in parsed.model_dump()
+
+
+def test_closed_enum_discriminator_still_rejects_bogus_value():
+    # Guard: opening up unknown *top-level* fields must not over-open a CLOSED
+    # enum. Pricing.model is a closed PricingModel enum; a bogus value must
+    # still raise (before AND after the fix).
+    with pytest.raises(ValidationError):
+        models.Pricing.model_validate({"model": "PRICING_MODEL_BOGUS"})