You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: specs/generators/pages/signed_doc/voting_process/proposals_templates_and_discovery.md.jinja
+83-29Lines changed: 83 additions & 29 deletions
Original file line number
Diff line number
Diff line change
@@ -24,12 +24,12 @@ and how all artifacts are discovered and validated in a decentralized pub/sub ne
24
24
25
25
* A Proposal references a Proposal Form Template via [`metadata.template`](../metadata.md#template)
26
26
and a system parameters anchor via [`metadata.parameters`](../metadata.md#parameters).
27
-
* The template’s own [`parameters`](../metadata.md#parameters) must transitively align to the
28
-
same Brand/Campaign/Category chain.
27
+
* The template’s own [`parameters`](../metadata.md#parameters) must transitively align to the
28
+
same Brand/Campaign/Category chain.
29
29
* A Proposal Submission Action references the Proposal via `metadata.ref` and repeats `metadata.parameters`,
30
-
linked to `ref` for consistency.
31
-
* Multiple collaborators may exist; all listed collaborators must submit equivalent `final`
32
-
actions to be considered final by the deadline.
30
+
linked to [`ref`](../metadata.md#ref) for consistency.
31
+
* Multiple collaborators may exist; all listed collaborators must submit equivalent `final`
32
+
actions to be considered final by the deadline.
33
33
34
34
The Deadline for a Proposal to be Final will be defined in the applicable parameters document(s),
35
35
typically the Category Parameters document.
@@ -46,26 +46,74 @@ typically the Category Parameters document.
46
46
47
47
## Pub/Sub Discovery Model
48
48
49
-
All documents are published in the appropriate topic as defined by specs/generators/pages/signed_doc/voting_process/parameters_hierarchy_and_discovery.md.jinja
50
-
and their parameters metadata.
51
-
52
-
To discover the proposal template, a client looks in the appropriate topic for unique document IDs of the proposal template type.
53
-
Then they choose the latest version of that template.
54
-
This allows a client to determine all the possible proposal templates which are enabled for a given brand, campaign or category.
55
-
Client applications then use the templates they discover to allow clients to submit proposal documents which match those templates.
56
-
The timing and allowability and other rules are defined by the appropriate prameters document and its parent parameters documents.
57
-
Once a proposal is submitted, its automatically draft.
58
-
It can be made final by the deadline (as defined by parameters).
59
-
If it is, it is a candidate proposal for a contest on the same parameter level.
60
-
However, the proposal may be moderated and not be allowed to be a candidate proposal for the contest if a moderation action is submitted against it.
61
-
Proposal comments may be attached to a proposal, and they may also be attached to another comment (acting as a reply).
62
-
In this case they must link to the same proposal. You cant reply to a proposal comment on a different proposal.
63
-
Comments can also be moderated via moderation actions. And in which case the client interface should hide them or show them as moderated and redacted.
64
-
Comments and proposals can be revoked by their authors.
65
-
When a proposal is revoked, all its comments should also be considered revoked, unless it is subsequently re-instated.
66
-
67
-
At the campaign moderation deadline, the final set of candidate proposals for the contest is determined.
68
-
These are then used in the contest voting process, described elsewhere.
49
+
### Overview
50
+
51
+
* Publication and topic routing are defined by the parameters anchor (brand/campaign/category).
52
+
See: [Parameters Hierarchy and Discovery](parameters_hierarchy_and_discovery.md) for topic
53
+
scope, naming, and subscription strategies.
54
+
* Producers publish each document to the topic derived from its `metadata.parameters`.
55
+
* Consumers subscribe to the relevant topics for their chosen anchor(s) and filter by document type.
56
+
57
+
### Discovery Workflow
58
+
59
+
1. Discover templates
60
+
* Subscribe to the anchor topic(s) and collect all
61
+
[Proposal Form Template](../docs/proposal_form_template.md) documents.
62
+
* For each `template.id`, select the latest `template.ver` (respecting `revocations`).
63
+
* The resulting set enumerates which proposal templates are enabled at the given anchor.
64
+
2. Discover proposals
65
+
* Collect or Publish new [Proposal](../docs/proposal.md) documents that reference one of the
66
+
discovered templates via `metadata.template`.
67
+
* Enforce that `metadata.parameters` on the proposal matches the anchor and links to the same
68
+
parameters chain as the template.
69
+
3. Ingest submission actions
70
+
* Collect [Proposal Submission Action](../docs/proposal_submission_action.md) documents by
71
+
proposal `metadata.ref`.
72
+
* Track the latest action per signer (author or listed collaborator): `final`, `draft`, or `hide`.
73
+
* A proposal is eligible to be “final” only if all required signers have a latest `final`
74
+
action by the configured deadline.
75
+
4. Apply moderation and policy
76
+
* If present, process [Proposal Moderation Action](../docs/proposal_moderation_action.md)
77
+
artifacts that may hide or disqualify proposals (policy‑dependent).
78
+
* Respect `hide` semantics from submission actions and moderation decisions in UI and candidate
79
+
selection.
80
+
5. Handle revocations
81
+
* Honor [`revocations`](../metadata.md#revocations) on proposals or related artifacts.
82
+
Implementations should treat comments under a revoked proposal as revoked for visibility,
83
+
unless the proposal is re‑instated.
84
+
6. Comments
85
+
* [Proposal Comment](../docs/proposal_comment.md) documents attach to a proposal;
86
+
replies attach to another comment.
87
+
* All comments and replies must link to the same proposal; cross‑proposal replies are invalid.
88
+
* Comments may be moderated via [Proposal Moderation Action](../docs/proposal_moderation_action.md)
89
+
and hidden/redacted accordingly.
90
+
91
+
### Finalization
92
+
93
+
* At the configured moderation/finalization deadline (from parameters), compute the final set of
94
+
candidate proposals for the contest at the same anchor level.
95
+
* The candidate set consists of proposals that are “final” (per signer unanimity) and not
96
+
disqualified by moderation.
97
+
* These candidates feed into the contest voting process (described in the voting flow documentation).
98
+
99
+
### Flow (Mermaid)
100
+
101
+
```mermaid
102
+
flowchart TD
103
+
A["Subscribe to Topics per Anchor<br/>(Brand/Campaign/Category)"] --> B[Discover Templates]
104
+
B --> C[Discover/Publish Proposals<br/>referencing template + parameters]
105
+
C --> D[Ingest/Publish Submission Actions<br/>author + collaborators]
106
+
D --> E{By deadline:<br/>all-final?}
107
+
E -- No --> F[Status: Draft/Hidden]
108
+
E -- Yes --> G[Status: Final Candidate]
109
+
C --> H[Ingest Moderation Actions]
110
+
H --> I{Moderated?}
111
+
I -- No --> K[No change]
112
+
I -- Yes --> J[Hide/Disqualify<br/>per policy]
113
+
G --> L[Candidate Set]
114
+
K --> L
115
+
L --> M[Contest Voting Inputs]
116
+
```
69
117
70
118
### Consumer Pipeline
71
119
@@ -82,20 +130,27 @@ These are then used in the contest voting process, described elsewhere.
82
130
* For each signer, record latest action: `final`, `draft`, or `hide`.
83
131
* A proposal is “final” iff all listed collaborators (and the author) have a latest
84
132
`final` action by the configured deadline.
133
+
4. Moderation Action intake (optional)
134
+
* Verify signature and policy scope; verify `metadata.ref` points to the intended proposal and
135
+
`metadata.parameters` matches.
136
+
* Apply moderation outcomes to proposal visibility and eligibility per policy.
85
137
86
138
### Status Computation
87
139
88
-
* Final Set: proposals with all required `final` actions, within configured windows defined by parameters.
140
+
* Final Set: proposals with all required `final` actions, within configured windows defined by
141
+
parameters, and not disqualified by moderation.
89
142
* Draft Only: proposals with at least one `draft` and no conflicting `final` from that signer.
90
-
* Hidden: honor `hide` semantics (author hides the proposal; collaborator hide = collaborator does not wish to be shown).
143
+
* Hidden: honor `hide` semantics (author hides the proposal; collaborator hide = collaborator does
144
+
not wish to be shown), and apply moderation decisions.
0 commit comments