feat(triparty): governed-triparty marketplace contract (netting cell + bundles)

Makefile

@@ -1,8 +1,12 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-triparty-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-triparty-examples
 	@echo "OK: validate"
 
+validate-triparty-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_triparty_examples.py
+
 validate-control-plane-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_control_plane_examples.py

examples/netting_cell.json

@@ -0,0 +1,36 @@
+{
+  "id": "urn:srcos:netting-cell:cu-trade-0001",
+  "type": "NettingCell",
+  "specVersion": "2.0.0",
+  "legs": [
+    {
+      "party": "urn:srcos:party:antofagasta-port",
+      "role": "A",
+      "valueRef": "asset://copper-cathode/500t",
+      "proofRef": "urn:srcos:attestation:antofagasta/bill-of-lading"
+    },
+    {
+      "party": "urn:srcos:party:shanghai-buyer",
+      "role": "B",
+      "valueRef": "asset://ASI/1.16M",
+      "capabilityRef": "cap://import-license/cn"
+    },
+    {
+      "party": "urn:srcos:party:clearing-verifier",
+      "role": "C",
+      "proofRef": "urn:srcos:attestation:route-anf-sha/delivery"
+    }
+  ],
+  "stage": "Verified",
+  "truthClass": "ATTESTED",
+  "admissibility": "release",
+  "bundleRefs": [
+    "urn:srcos:triparty-bundle:cu-trade-0001-fill",
+    "urn:srcos:triparty-bundle:cu-trade-0001-verify"
+  ],
+  "policyKernelRef": "policy://triparty/release-guard",
+  "reserveRef": "reserve://asi/primary",
+  "netAmount": 1160000,
+  "asset": "ASI",
+  "supplyChainRef": "hg:route/anf-sha"
+}

examples/triparty_bundle.json

@@ -0,0 +1,16 @@
+{
+  "id": "urn:srcos:triparty-bundle:cu-trade-0001-verify",
+  "type": "TripartyBundle",
+  "specVersion": "2.0.0",
+  "kind": "verification",
+  "cellRef": "urn:srcos:netting-cell:cu-trade-0001",
+  "payload": {
+    "verifier": "clearing-verifier",
+    "result": "delivery-confirmed",
+    "scope": "route-anf-sha"
+  },
+  "proofRef": "urn:srcos:proof:cu-trade-0001/state",
+  "attestationRef": "urn:srcos:attestation:route-anf-sha/delivery",
+  "truthClass": "ATTESTED",
+  "issuedAt": "2026-07-03T18:00:00Z"
+}

schemas/NettingCell.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/NettingCell.json",
+  "title": "NettingCell",
+  "description": "A governed triparty netting cell — the smallest local clearing object that couples value, proof, authority, and disclosure. Cancels interior circulation across three legs and governs release/refund/export by policy rather than confidence alone.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "legs",
+    "stage",
+    "truthClass",
+    "admissibility"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:netting-cell:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:netting-cell:<local-id>"
+    },
+    "type": {
+      "const": "NettingCell",
+      "description": "Discriminator constant — always \"NettingCell\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version, e.g. \"2.0.0\"."
+    },
+    "legs": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "party",
+          "role"
+        ],
+        "properties": {
+          "party": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Party URN / identifier for this leg."
+          },
+          "role": {
+            "type": "string",
+            "enum": [
+              "A",
+              "B",
+              "C"
+            ],
+            "description": "Triparty leg role (A, B are counterparties; C is the clearing/verifier leg)."
+          },
+          "valueRef": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The monetary/asset value this leg carries into the cell."
+          },
+          "capabilityRef": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The capability right this leg carries (from the CapabilityRegistry) — kept distinct from value."
+          },
+          "proofRef": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The proof/attestation this leg carries (Truth Engine) — evidence distinct from permission."
+          }
+        }
+      },
+      "description": "The three triparty legs (A, B counterparties; C clearing/verifier)."
+    },
+    "stage": {
+      "type": "string",
+      "enum": [
+        "Observed",
+        "Proposed",
+        "Ready",
+        "Escrowed",
+        "Filled",
+        "Verified",
+        "Released",
+        "Exported",
+        "Refunded",
+        "Reversed"
+      ],
+      "description": "Lifecycle stage: Observed→Proposed→Ready→Escrowed→Filled→Verified→Released→(Exported); or Refunded/Reversed."
+    },
+    "truthClass": {
+      "type": "string",
+      "enum": [
+        "PROVEN",
+        "ATTESTED",
+        "INFERRED",
+        "REPUTED"
+      ],
+      "description": "Truth class of the cell's current state (constitution): PROVEN⊐ATTESTED⊐INFERRED⊐REPUTED."
+    },
+    "admissibility": {
+      "type": "string",
+      "enum": [
+        "evidence",
+        "admit",
+        "release",
+        "export"
+      ],
+      "description": "Current admissibility ceiling on the lattice evidence⊇admit⊇release⊇export. Export is stricter than local validity."
+    },
+    "bundleRefs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^urn:srcos:triparty-bundle:"
+      },
+      "description": "The typed bundles that moved this cell through its lifecycle."
+    },
+    "policyKernelRef": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The PolicyKernel that disposes release/refund/export (policy disposes; evidence proposes; proof preserves)."
+    },
+    "reserveRef": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "ReserveManager reference backing settlement."
+    },
+    "netAmount": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Net residual after interior cancellation."
+    },
+    "asset": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Settlement asset / token (e.g. ASI/FET)."
+    },
+    "supplyChainRef": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Optional hg: / node ref when this cell clears a supply-chain trade."
+    }
+  }
+}

schemas/TripartyBundle.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/TripartyBundle.json",
+  "title": "TripartyBundle",
+  "description": "A typed, proof-carrying bundle that moves a netting cell through one lifecycle step. Bundle kinds mirror the settlement flow; each carries payload + proof + attestation so release is a function of evidence, admissibility, and freshness — not confidence.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "kind",
+    "cellRef",
+    "payload",
+    "truthClass"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:triparty-bundle:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:triparty-bundle:<local-id>"
+    },
+    "type": {
+      "const": "TripartyBundle",
+      "description": "Discriminator constant — always \"TripartyBundle\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version, e.g. \"2.0.0\"."
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "intent",
+        "acceptance",
+        "escrow",
+        "fill",
+        "verification",
+        "export"
+      ],
+      "description": "Bundle kind: intent→acceptance→escrow→fill→verification→export."
+    },
+    "cellRef": {
+      "type": "string",
+      "pattern": "^urn:srcos:netting-cell:",
+      "description": "The netting cell this bundle advances."
+    },
+    "payload": {
+      "type": "object",
+      "description": "Kind-specific payload (terms, fill metadata, verification result, export scope)."
+    },
+    "proofRef": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Packet/state proof (freshness, replay-safety)."
+    },
+    "attestationRef": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Witness/attestation (provenance + independence) — the Truth Record backing this bundle."
+    },
+    "truthClass": {
+      "type": "string",
+      "enum": [
+        "PROVEN",
+        "ATTESTED",
+        "INFERRED",
+        "REPUTED"
+      ],
+      "description": "Truth class this bundle asserts."
+    },
+    "issuedAt": {
+      "type": "string",
+      "description": "ISO-8601 issue time (freshness)."
+    }
+  }
+}

tools/validate_triparty_examples.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Validate the governed-triparty marketplace contract examples.
+
+Covers the settlement/marketplace primitives: NettingCell (the triparty clearing
+cell that couples value + proof + authority + disclosure) and TripartyBundle (the
+typed, proof-carrying bundle that advances a cell through its lifecycle).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import jsonschema
+
+ROOT = Path(__file__).resolve().parents[1]
+PAIRS = [
+    (ROOT / "schemas" / "NettingCell.json", ROOT / "examples" / "netting_cell.json"),
+    (ROOT / "schemas" / "TripartyBundle.json", ROOT / "examples" / "triparty_bundle.json"),
+]
+
+
+def validate_pair(schema_path: Path, example_path: Path) -> None:
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    jsonschema.validators.validator_for(schema).check_schema(schema)
+    example = json.loads(example_path.read_text(encoding="utf-8"))
+    jsonschema.validate(example, schema)
+
+
+def main() -> int:
+    checks: dict[str, bool] = {}
+    for schema_path, example_path in PAIRS:
+        validate_pair(schema_path, example_path)
+        checks[example_path.name] = True
+    print(json.dumps({"ok": all(checks.values()), "checks": checks}, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())