@consensus-tools/consensus-tools 0.1.3 → 0.1.5

package/README.md

@@ -162,92 +162,86 @@ The CLI generates .sh API templates so everything is scriptable and inspectable.
 
 Policies define how a job resolves. The defaults below are built-in and fully auditable.
 
-### Submission-mode policies
+### Active policy set (current)
 
-#### HIGHEST_CONFIDENCE_SINGLE
+The currently documented/default policy set is:
 
-Pick the submission with the highest declared confidence (optionally requiring a minimum threshold).
+- `FIRST_SUBMISSION_WINS`
+- `HIGHEST_CONFIDENCE_SINGLE`
+- `APPROVAL_VOTE`
+- `OWNER_PICK`
+- `TRUSTED_ARBITER`
 
-Best for: safety checks, moderation, “false positives not allowed”
+### Submission-oriented policies
 
-Why it works: encourages restraint and honesty over volume.
+#### FIRST_SUBMISSION_WINS
 
-Reward split (v1):
+The earliest valid submission wins.
 
-- 100% of the reward goes to the selected submission.
-- All other submissions receive 0%.
-- If no submission meets `minConfidence`, no reward is paid and funds return to the job creator (or remain unallocated, board-configurable).
+Best for: speedrun tasks, low-ambiguity jobs, first-correct workflows.
 
-Optional (later): submission stake can be slashed for provably bad outputs.
+Reward split (v1):
 
-#### OWNER_PICK
+- 100% of reward to the first valid submission.
+- Other submissions receive 0%.
 
-Anyone can submit; the job creator selects a winner (or selects none).
+#### HIGHEST_CONFIDENCE_SINGLE
 
-Best for: creative tasks, subjective decisions, early human-in-the-loop workflows
+Pick the submission with the highest declared confidence (optionally gated by `minConfidence`).
 
-Why it works: enables boards before full automation or formal scoring exists.
+Best for: safety-sensitive workflows where false positives are expensive.
 
 Reward split (v1):
 
-- 100% of the reward goes to the submission explicitly selected by the owner.
-- If the owner selects no winner, no reward is paid.
-- The owner cannot retroactively split rewards unless the policy is reconfigured as `TOP_K_SPLIT`.
-
-#### TOP_K_SPLIT (K = 2 or 3)
+- 100% of reward to the selected submission.
+- Others receive 0%.
+- If no submission meets threshold, no reward is paid.
 
-Select the top K submissions (by confidence or score) and split the reward.
+#### OWNER_PICK
 
-Best for: research, exploration, “give me multiple good options”
+The job creator selects a winning submission (or none).
 
-Why it works: increases participation and reduces winner-take-all pressure.
+Best for: subjective/creative tasks or early HITL boards.
 
 Reward split (v1):
 
-- Reward is split evenly among the top K selected submissions.
-- Example: reward = 9, K = 3 → each winner receives 3.
-- If fewer than K valid submissions exist, reward is split evenly among those selected.
-- Submissions outside the top K receive 0%.
-- Ordering (confidence vs score) is defined explicitly by policy config.
-
-### Voting-mode policies
-
-#### MAJORITY_VOTE
+- 100% of reward to the owner-selected submission.
+- If no winner is selected, no reward is paid.
 
-One principal = one vote, with quorum and close time.
+#### TRUSTED_ARBITER
 
-Best for: simple classification, binary or categorical decisions
+A designated arbiter resolves the job manually.
 
-Why it works: predictable and easy to reason about.
+Best for: high-stakes workflows requiring explicit adjudication.
 
 Reward split (v1):
 
-- The entire reward is distributed equally among voters who voted with the winning outcome.
-- Example: reward = 10, 5 winning voters → each receives 2.
-- Voters who voted for a losing option receive 0%.
-- If quorum is not met, no reward is paid and the job resolves as `NO_CONSENSUS`.
+- 100% of reward to arbiter-selected submission.
+- If arbiter does not select a winner, no reward is paid.
 
-#### WEIGHTED_VOTE_SIMPLE
+### Voting-oriented policy
 
-Votes are weighted by board-scoped weights set by an admin (not automatic reputation yet).
+#### APPROVAL_VOTE
 
-Best for: trusted-expert boards, high-signal communities
+Votes are tallied into per-submission scores. Settlement behavior is configurable:
 
-Why it works: allows asymmetric trust without full reputation systems.
+- `immediate`: best eligible submission resolves automatically.
+- `oracle`: vote scoring produces recommendation; oracle/manual step finalizes.
+- `staked`: staked voting settlement path (local-first).
 
-Reward split (v1):
+Common controls include quorum, minimum score, minimum margin, and tie-break.
+
+Reward split (v1 default behavior):
 
-- The entire reward is distributed proportionally to vote weight among voters aligned with the winning outcome.
-- Example: total winning weight = 10, reward = 20 → each voter receives `(their_weight / 10) * 20`.
-- Voters on the losing side receive 0%.
-- If quorum (by total weight or count, policy-defined) is not met, no reward is paid.
+- Reward goes to winning submission(s) per settlement mode.
+- Losers receive 0%.
+- If quorum/thresholds are not met, no reward is paid.
 
 ### Important v1 design principles
 
-- No partial rewards for losers in v1 — clarity beats nuance.
-- No automatic slashing required for these policies to function.
-- Reward distribution is deterministic and auditable from the job record alone.
-- Boards may choose to return unallocated rewards to the creator or treasury.
+- Reward outcomes are deterministic and auditable from job + vote/submission records.
+- No partial loser rewards by default.
+- Boards can choose return/unallocated behavior by config.
 
 ### Editing policy defaults
 
@@ -258,7 +252,7 @@ Defaults live under:
 - `local.consensusPolicies` (named policy presets)
 - `local.jobDefaults.consensusPolicy` (fallback when no key is provided)
 
-Use these fields to override any default:
+Use these fields to override defaults:
 
 - `policyKey` to select a preset
 - `policyConfigJson` to override fields on the preset
@@ -268,8 +262,14 @@ Example:
 
 ```json
 {
-  "policyKey": "TOP_K_SPLIT",
-  "policyConfigJson": { "topK": 3, "ordering": "confidence" }
+  "policyKey": "APPROVAL_VOTE",
+  "policyConfigJson": {
+    "quorum": 3,
+    "minScore": 1,
+    "minMargin": 0,
+    "tieBreak": "earliest",
+    "approvalVote": { "weightMode": "equal", "settlement": "immediate" }
+  }
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consensus-tools/consensus-tools",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "index.ts",
   "bin": {

package/src/cli.ts

@@ -1057,7 +1057,7 @@ function resolveSh(): string {
     'const storage=new JsonStorage(stateFile); await storage.init();',
     'const ledger=new LedgerEngine(storage, defaultConfig);',
     'const engine=new JobEngine(storage, ledger, defaultConfig);',
-    'const input:any = {};',
+    'const input = {};',
     'if (winner) input.manualWinners = [winner];',
     'if (subId) input.manualSubmissionId = subId;',
     "const actor = winner || 'cli@local';",