docs(docs): wip

Author: stevenj

specs/generators/pages/signed_doc/voting_process/proposals_templates_and_discovery.md.jinja

@@ -0,0 +1,112 @@
+---
+Title: Proposals, Templates, and Pub/Sub Discovery
+Authors:
+    - Steven Johnson <steven[email protected]>
+Created: 2025-11-05
+order: 2
+---
+
+## Abstract
+
+Shows how Proposal documents relate to their Templates, how submission state is determined, 
+and how all artifacts are discovered and validated in a decentralized pub/sub network.
+
+## Documents and Roles
+
+* [Proposal](../docs/proposal.md): the authored content.
+* [Proposal Form Template](../docs/proposal_form_template.md): defines schema and form hints.
+* [Proposal Submission Action](../docs/proposal_submission_action.md): signals `final`, `draft`, or `hide`.
+* *Optional [Proposal Comment](../docs/proposal_comment.md)* and 
+  *[Proposal Comment Form Template](../docs/proposal_comment_form_template.md)* artifacts exist;
+* *Optional [Proposal Moderation Action](../docs/proposal_moderation_action.md)* artifacts exist;
+
+## Relationships
+
+* A Proposal references a Proposal Form Template via [`metadata.template`](../metadata.md#template)
+  and a system parameters anchor via [`metadata.parameters`](../metadata.md#parameters).
+   * The template’s own [`parameters`](../metadata.md#parameters) must transitively align to the 
+     same Brand/Campaign/Category chain. 
+* A Proposal Submission Action references the Proposal via `metadata.ref` and repeats `metadata.parameters`, 
+  linked to `ref` for consistency.
+   * Multiple collaborators may exist; all listed collaborators must submit equivalent `final` 
+     actions to be considered final by the deadline.
+
+The Deadline for a Proposal to be Final will be defined in the applicable parameters document(s),
+typically the Category Parameters document.
+
+## Versioning and Collaboration
+
+* Proposal [`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) are UUIDv7.
+* The first Proposal version must be signed by the original author;
+  later versions may be signed by the author or a collaborator from the immediately prior version. 
+  See: [Proposal validation](../docs/proposal.md#validation).
+* Collaborators are listed in `metadata.collaborators`; 
+  actions from collaborators confirm or rescind participation.
+  See: [Proposal Submission Action](../docs/proposal_submission_action.md).
+
+## Pub/Sub Discovery Model
+
+All documents are published in the appropriate topic as defined by specs/generators/pages/signed_doc/voting_process/parameters_hierarchy_and_discovery.md.jinja
+and their parameters metadata.
+
+To discover the proposal template, a client looks in the appropriate topic for unique document IDs of the proposal template type.
+Then they choose the latest version of that template.
+This allows a client to determine all the possible proposal templates which are enabled for a given brand, campaign or category.
+Client applications then use the templates they discover to allow clients to submit proposal documents which match those templates.
+The timing and allowability and other rules are defined by the appropriate prameters document and its parent parameters documents.
+Once a proposal is submitted, its automatically draft.
+It can be made final by the deadline (as defined by parameters).
+If it is, it is a candidate proposal for a contest on the same parameter level.
+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.
+Proposal comments may be attached to a proposal, and they may also be attached to another comment (acting as a reply).
+In this case they must link to the same proposal.  You cant reply to a proposal comment on a different proposal.
+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.
+Comments and proposals can be revoked by their authors.
+When a proposal is revoked, all its comments should also be considered revoked, unless it is subsequently re-instated.
+
+At the campaign moderation deadline, the final set of candidate proposals for the contest is determined.
+These are then used in the contest voting process, described elsewhere.
+
+### Consumer Pipeline
+
+1. Template intake
+    * Verify signature, type, id/ver, `metadata.parameters`, and payload schema validity.
+    * Index by `(template-id, ver)` and by anchor.
+2. Proposal intake
+    * Verify signature, `metadata.template`, `metadata.parameters` (linked to template), 
+      and payload against the template schema.
+    * Track authorship and collaborators; index by `(proposal-id, ver)` and by anchor.
+3. Submission Action intake
+    * Verify signature from author or collaborator; verify `metadata.ref` 
+      points to the intended proposal and `metadata.parameters` matches (linked_refs to `ref`).
+    * For each signer, record latest action: `final`, `draft`, or `hide`.
+    * A proposal is “final” iff all listed collaborators (and the author) have a latest 
+      `final` action by the configured deadline.
+
+### Status Computation
+
+* Final Set: proposals with all required `final` actions, within configured windows defined by parameters.
+* Draft Only: proposals with at least one `draft` and no conflicting `final` from that signer.
+* Hidden: honor `hide` semantics (author hides the proposal; collaborator hide = collaborator does not wish to be shown).
+
+## Validation Summary
+
+* Verify `type`, `id`, `ver`, `kid`, `content type`, and (if present) `content-encoding`.
+* Verify `metadata.template` exists and aligns via `metadata.parameters` up the same chain.
+* Validate the proposal payload against the referenced template JSON Schema.
+* For submission actions, enforce signer rules and collaborator unanimity for `final`.
+* Apply `revocations` and prefer the highest valid `ver` per `id`.
+
+## Content Addressing and Retrieval
+
+* All documents carry a `document_ref` that includes a CBOR Tag 42 CID locator. 
+  See: [Document Reference](../metadata.md#document-reference).
+* Pub/sub provides dissemination; the CID enables retrieval from content-addressed 
+  storage and ensures immutability.
+
+## Operational Notes
+
+* Timelines and windows come from the applicable parameters (brand/campaign/category/contest); 
+  consumers should enforce submission cutoffs as configured.
+* Indexes: maintain by proposal, by anchor, and by template to accelerate UI queries.
+