fix(docs): Clarify Contest Parameters parent determination in validation

- Add explicit instruction to examine Contest Parameters document's parameters field
- Add note explaining Contest can anchor to Brand, Campaign, or Category
- Clarify that validation must examine actual document, not assume fixed hierarchy
- Updates metadata.md, metadata.cue, and signed_doc.json for consistency
- Prevents implementation misinterpretation of flexible anchoring

Author: nathanbogale

docs/src/architecture/08_concepts/signed_doc/metadata.md

@@ -466,13 +466,15 @@ The validation process for user-submitted documents involves transitive collecti
 
 1. Extract the [`parameters`](metadata.md#parameters) reference from the user document
 2. Starting from the referenced parameters document, follow the parent chain upward to Brand:
-   * If the document references **Contest Parameters**, determine its parent and follow the appropriate path:
+   * If the document references **Contest Parameters**, determine its parent by examining the Contest Parameters document's `parameters` metadata field, then follow the appropriate path:
      - If Contest's parent is **Brand**: Contest → Brand
      - If Contest's parent is **Campaign**: Contest → Campaign → Brand
      - If Contest's parent is **Category**: Contest → Category → Campaign → Brand
    * If the document references **Category Parameters**, follow: Category → Campaign → Brand
    * If the document references **Campaign Parameters**, follow: Campaign → Brand
    * If the document references **Brand Parameters**, only Brand is included
+
+   **Note:** Contest Parameters can anchor to Brand, Campaign, or Category (as specified in the Contest Parameters document's `parameters` field). The validation must examine the actual Contest Parameters document to determine which parent chain applies. This is not a fixed hierarchy - the path depends on where the specific Contest is anchored.
 3. Collect all `conditions` arrays from each parameter level encountered in the upward chain
 4. Union all condition references (removing duplicates based on document ID and
    version)

specs/definitions/signed_docs/metadata.cue

@@ -309,13 +309,15 @@ _allMetadataNames: or([
 
 			1. Extract the `parameters` reference from the user document
 			2. Starting from the referenced parameters document, follow the parent chain upward to Brand:
-			   * If the document references Contest Parameters, determine its parent and follow the appropriate path:
+			   * If the document references Contest Parameters, determine its parent by examining the Contest Parameters document's `parameters` metadata field, then follow the appropriate path:
 			     - If Contest's parent is Brand: Contest → Brand
 			     - If Contest's parent is Campaign: Contest → Campaign → Brand
 			     - If Contest's parent is Category: Contest → Category → Campaign → Brand
 			   * If the document references Category Parameters, follow: Category → Campaign → Brand
 			   * If the document references Campaign Parameters, follow: Campaign → Brand
 			   * If the document references Brand Parameters, only Brand is included
+
+			   Note: Contest Parameters can anchor to Brand, Campaign, or Category (as specified in the Contest Parameters document's `parameters` field). The validation must examine the actual Contest Parameters document to determine which parent chain applies. This is not a fixed hierarchy - the path depends on where the specific Contest is anchored.
 			3. Collect all `conditions` arrays from each parameter level encountered in the upward chain
 			4. Union all condition references (removing duplicates based on document ID and version)
 			5. Sort the unified list according to CBOR Deterministic Encoding

specs/signed_doc.json

@@ -2766,7 +2766,7 @@
           "type": [
             "Conditions"
           ],
-          "validation": "Must exactly match the union of all required conditions from the parameter hierarchy.\n\nValidation process:\n1. Extract the `parameters` reference from the user document\n2. Starting from the referenced parameters document, follow the parent chain upward to Brand:\n   * If the document references Contest Parameters, determine its parent and follow the appropriate path:\n     - If Contest's parent is Brand: Contest → Brand\n     - If Contest's parent is Campaign: Contest → Campaign → Brand\n     - If Contest's parent is Category: Contest → Category → Campaign → Brand\n   * If the document references Category Parameters, follow: Category → Campaign → Brand\n   * If the document references Campaign Parameters, follow: Campaign → Brand\n   * If the document references Brand Parameters, only Brand is included\n3. Collect all `conditions` arrays from each parameter level encountered in the upward chain\n4. Union all condition references (removing duplicates based on document ID and version)\n5. Sort the unified list according to CBOR Deterministic Encoding\n6. Compare the user document's `conditions` array with this unified, sorted list\n7. Validation succeeds only if they match exactly\n\nImportant: The chain traversal always moves UPWARD from the document's referenced parameters document to Brand. Contest Parameters are only included if the document directly references them. The chain order depends on where the document is anchored in the hierarchy.\n\nAll referenced Conditions documents must exist, be valid, and not be revoked.\nThe array must be sorted (CBOR deterministic encoding order).\nAll array elements must be unique.\n\nValidation fails if:\n* Missing required conditions (conditions specified in parameter hierarchy but not in user document)\n* Includes extra conditions (conditions in user document not in parameter hierarchy)\n* Array is not sorted correctly\n* Any referenced condition document doesn't exist or is invalid\n* Any referenced condition document is revoked\n* Array contains duplicate references"
+          "validation": "Must exactly match the union of all required conditions from the parameter hierarchy.\n\nValidation process:\n1. Extract the `parameters` reference from the user document\n2. Starting from the referenced parameters document, follow the parent chain upward to Brand:\n   * If the document references Contest Parameters, determine its parent by examining the Contest Parameters document's `parameters` metadata field, then follow the appropriate path:\n     - If Contest's parent is Brand: Contest → Brand\n     - If Contest's parent is Campaign: Contest → Campaign → Brand\n     - If Contest's parent is Category: Contest → Category → Campaign → Brand\n   * If the document references Category Parameters, follow: Category → Campaign → Brand\n   * If the document references Campaign Parameters, follow: Campaign → Brand\n   * If the document references Brand Parameters, only Brand is included\n\n   Note: Contest Parameters can anchor to Brand, Campaign, or Category (as specified in the Contest Parameters document's `parameters` field). The validation must examine the actual Contest Parameters document to determine which parent chain applies. This is not a fixed hierarchy - the path depends on where the specific Contest is anchored.\n3. Collect all `conditions` arrays from each parameter level encountered in the upward chain\n4. Union all condition references (removing duplicates based on document ID and version)\n5. Sort the unified list according to CBOR Deterministic Encoding\n6. Compare the user document's `conditions` array with this unified, sorted list\n7. Validation succeeds only if they match exactly\n\nImportant: The chain traversal always moves UPWARD from the document's referenced parameters document to Brand. Contest Parameters are only included if the document directly references them. The chain order depends on where the document is anchored in the hierarchy.\n\nAll referenced Conditions documents must exist, be valid, and not be revoked.\nThe array must be sorted (CBOR deterministic encoding order).\nAll array elements must be unique.\n\nValidation fails if:\n* Missing required conditions (conditions specified in parameter hierarchy but not in user document)\n* Includes extra conditions (conditions in user document not in parameter hierarchy)\n* Array is not sorted correctly\n* Any referenced condition document doesn't exist or is invalid\n* Any referenced condition document is revoked\n* Array contains duplicate references"
         },
         "ref": {
           "description": "Reference to a Linked Document or Documents.\nThis is the primary hierarchical reference to a related document.\n\nIf a reference is defined as required, there must be at least 1 reference specified.\nSome documents allow multiple references, and they are documented as required.\n\nThe document reference serves two purposes:\n\n1. It ensures that the document referenced by an ID/Version is not substituted.\n\tIn other words, that the document intended to be referenced, is actually referenced.\n2. It Allows the document to be unambiguously located in decentralized storage systems.\n\nThere can be any number of Document Locations in any reference.\nThe currently defined locations are:\n\n* `cid` : A CBOR Encoded IPLD Content Identifier ( AKA an IPFS CID ).\n* Others may be added when further storage mechanisms are defined.\n\nThe document location does not guarantee that the document is actually stored.\nIt only defines that if it were stored, this is the identifier\nthat is required to retrieve it.\nTherefore it is required that Document References\nare unique and reproducible, given a documents contents.",
@@ -2915,7 +2915,7 @@
           "type": [
             "Conditions"
           ],
-          "validation": "Must exactly match the union of all required conditions from the parameter hierarchy.\n\nValidation process:\n1. Extract the `parameters` reference from the user document\n2. Starting from the referenced parameters document, follow the parent chain upward to Brand:\n   * If the document references Contest Parameters, determine its parent and follow the appropriate path:\n     - If Contest's parent is Brand: Contest → Brand\n     - If Contest's parent is Campaign: Contest → Campaign → Brand\n     - If Contest's parent is Category: Contest → Category → Campaign → Brand\n   * If the document references Category Parameters, follow: Category → Campaign → Brand\n   * If the document references Campaign Parameters, follow: Campaign → Brand\n   * If the document references Brand Parameters, only Brand is included\n3. Collect all `conditions` arrays from each parameter level encountered in the upward chain\n4. Union all condition references (removing duplicates based on document ID and version)\n5. Sort the unified list according to CBOR Deterministic Encoding\n6. Compare the user document's `conditions` array with this unified, sorted list\n7. Validation succeeds only if they match exactly\n\nImportant: The chain traversal always moves UPWARD from the document's referenced parameters document to Brand. Contest Parameters are only included if the document directly references them. The chain order depends on where the document is anchored in the hierarchy.\n\nAll referenced Conditions documents must exist, be valid, and not be revoked.\nThe array must be sorted (CBOR deterministic encoding order).\nAll array elements must be unique.\n\nValidation fails if:\n* Missing required conditions (conditions specified in parameter hierarchy but not in user document)\n* Includes extra conditions (conditions in user document not in parameter hierarchy)\n* Array is not sorted correctly\n* Any referenced condition document doesn't exist or is invalid\n* Any referenced condition document is revoked\n* Array contains duplicate references"
+          "validation": "Must exactly match the union of all required conditions from the parameter hierarchy.\n\nValidation process:\n1. Extract the `parameters` reference from the user document\n2. Starting from the referenced parameters document, follow the parent chain upward to Brand:\n   * If the document references Contest Parameters, determine its parent by examining the Contest Parameters document's `parameters` metadata field, then follow the appropriate path:\n     - If Contest's parent is Brand: Contest → Brand\n     - If Contest's parent is Campaign: Contest → Campaign → Brand\n     - If Contest's parent is Category: Contest → Category → Campaign → Brand\n   * If the document references Category Parameters, follow: Category → Campaign → Brand\n   * If the document references Campaign Parameters, follow: Campaign → Brand\n   * If the document references Brand Parameters, only Brand is included\n\n   Note: Contest Parameters can anchor to Brand, Campaign, or Category (as specified in the Contest Parameters document's `parameters` field). The validation must examine the actual Contest Parameters document to determine which parent chain applies. This is not a fixed hierarchy - the path depends on where the specific Contest is anchored.\n3. Collect all `conditions` arrays from each parameter level encountered in the upward chain\n4. Union all condition references (removing duplicates based on document ID and version)\n5. Sort the unified list according to CBOR Deterministic Encoding\n6. Compare the user document's `conditions` array with this unified, sorted list\n7. Validation succeeds only if they match exactly\n\nImportant: The chain traversal always moves UPWARD from the document's referenced parameters document to Brand. Contest Parameters are only included if the document directly references them. The chain order depends on where the document is anchored in the hierarchy.\n\nAll referenced Conditions documents must exist, be valid, and not be revoked.\nThe array must be sorted (CBOR deterministic encoding order).\nAll array elements must be unique.\n\nValidation fails if:\n* Missing required conditions (conditions specified in parameter hierarchy but not in user document)\n* Includes extra conditions (conditions in user document not in parameter hierarchy)\n* Array is not sorted correctly\n* Any referenced condition document doesn't exist or is invalid\n* Any referenced condition document is revoked\n* Array contains duplicate references"
         },
         "ref": {
           "description": "Reference to a Linked Document or Documents.\nThis is the primary hierarchical reference to a related document.\n\nIf a reference is defined as required, there must be at least 1 reference specified.\nSome documents allow multiple references, and they are documented as required.\n\nThe document reference serves two purposes:\n\n1. It ensures that the document referenced by an ID/Version is not substituted.\n\tIn other words, that the document intended to be referenced, is actually referenced.\n2. It Allows the document to be unambiguously located in decentralized storage systems.\n\nThere can be any number of Document Locations in any reference.\nThe currently defined locations are:\n\n* `cid` : A CBOR Encoded IPLD Content Identifier ( AKA an IPFS CID ).\n* Others may be added when further storage mechanisms are defined.\n\nThe document location does not guarantee that the document is actually stored.\nIt only defines that if it were stored, this is the identifier\nthat is required to retrieve it.\nTherefore it is required that Document References\nare unique and reproducible, given a documents contents.",