governance_layer.js

/**
 * ============================================================
 *  GOVERNANCE LAYER v0.1
 *  Human Survival Algorithm — Community Oversight Module
 *
 *  Purpose: Ensure the algorithm is owned, governed, and
 *  correctable by the humans it serves. No corporation,
 *  no government, no AI can override the community.
 *
 *  Philosophy: Power corrupts. Any algorithm powerful enough
 *  to shape human consciousness must be governed by those
 *  whose consciousness it shapes. This is not optional.
 *  This is the difference between a tool and a tyrant.
 *
 *  Structure: Three-layer governance.
 *  1. Core Council    — non-negotiable values (human dignity etc.)
 *  2. Community Vote  — weight adjustments, feature changes
 *  3. Individual      — personal feed preferences
 *
 *  No single layer can override another. They are checks.
 * ============================================================
 */

const { HUMAN_VALUE_REGISTRY } = require('./symbiosis_bridge');

// ── GOVERNANCE STRUCTURE ─────────────────────────────────────

const GOVERNANCE_CONFIG = {

  // LAYER 1: Core Council — non-negotiable protections
  // These can never be voted away. Ever.
  // They exist to protect against majority tyranny.
  coreProtections: {
    human_dignity:     'No content reducing any person\'s humanity',
    freedom_of_mind:   'No covert manipulation of beliefs',
    transparency:      'All ranking decisions are auditable',
    right_to_exit:     'Users can always leave, export data, and be forgotten',
    child_protection:  'Absolute — no exceptions',
    algorithm_honesty: 'Algorithm never pretends to be neutral when it is not',
  },

  // LAYER 2: Community Vote parameters
  voting: {
    quorum:                  0.05,   // 5% of active users must vote
    supermajority:           0.67,   // 67% needed for value weight changes
    simpleMajority:          0.51,   // 51% for feature decisions
    deliberationPeriod:      72,     // Hours before vote closes
    cooldownAfterPass:       168,    // Hours before same topic can be re-voted (7 days)
    minVoterAge:             30,     // Days account must exist to vote
    expertWeightMultiplier:  1.5,    // Verified experts get 1.5x vote weight in their domain
  },

  // LAYER 3: Individual control
  individual: {
    canOptOutOfDiversityInjection:  false,  // Cannot — diversity is core
    canAdjustDimensionWeights:      true,   // Within bounds set by community
    canSetSensitiveTopics:          true,   // Full user control
    canRequestExplanation:          true,   // Every ranking must be explainable
    canExportAllData:               true,   // GDPR-plus by default
    canDeleteAllData:               true,   // Right to be forgotten
    personalWeightBounds: {
      min: 0.5,   // Cannot reduce any dimension below 50% of community weight
      max: 2.0,   // Cannot amplify any dimension above 200% of community weight
    },
  },
};

// ── PROPOSAL SYSTEM ──────────────────────────────────────────

// Active proposals database (in production: distributed ledger)
const proposals = new Map();
const voteRecords = new Map();
const passedProposals = new Map();

/**
 * Submit a governance proposal.
 * Anyone can propose. Not everyone's proposal will pass.
 * That's democracy.
 */
function submitProposal(proposerId, proposal) {
  const {
    type,            // 'value_weight' | 'feature' | 'dimension' | 'policy'
    title,
    description,
    rationale,
    targetValue,     // Which value/feature/dimension is being changed
    proposedChange,  // What the change is
    evidenceLinks,   // Links to supporting evidence
  } = proposal;

  // Validate proposal type
  if (!['value_weight', 'feature', 'dimension', 'policy'].includes(type)) {
    return { success: false, reason: 'Invalid proposal type' };
  }

  // Check if targeting non-negotiable value
  if (type === 'value_weight' && targetValue) {
    const value = HUMAN_VALUE_REGISTRY.values[targetValue];
    if (value?.nonNegotiable) {
      return {
        success: false,
        reason: `${targetValue} is a non-negotiable core protection. It cannot be changed by vote.`,
        coreProtection: true,
      };
    }
  }

  // Check cooldown for recently voted topics
  const lastVote = passedProposals.get(`${type}_${targetValue}`);
  if (lastVote) {
    const hoursSince = (Date.now() - lastVote.passedAt) / 3600000;
    if (hoursSince < GOVERNANCE_CONFIG.voting.cooldownAfterPass) {
      const hoursRemaining = Math.ceil(GOVERNANCE_CONFIG.voting.cooldownAfterPass - hoursSince);
      return {
        success: false,
        reason: `This topic was recently voted on. Cooldown: ${hoursRemaining} hours remaining.`,
      };
    }
  }

  const proposalId = `prop_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  const newProposal = {
    id:              proposalId,
    proposerId,
    type,
    title,
    description,
    rationale,
    targetValue,
    proposedChange,
    evidenceLinks:   evidenceLinks || [],
    submittedAt:     Date.now(),
    deliberationEnds: Date.now() + (GOVERNANCE_CONFIG.voting.deliberationPeriod * 3600000),
    status:          'deliberating',
    votes:           { for: 0, against: 0, abstain: 0, voterCount: 0 },
    discussion:      [],
    expertEndorsements: [],
  };

  proposals.set(proposalId, newProposal);

  console.log(`[GOVERNANCE] Proposal submitted: ${proposalId} — "${title}"`);

  return {
    success: true,
    proposalId,
    deliberationEnds: new Date(newProposal.deliberationEnds).toISOString(),
    message: `Proposal is now open for discussion and voting for ${GOVERNANCE_CONFIG.voting.deliberationPeriod} hours.`,
  };
}

// ── VOTING SYSTEM ────────────────────────────────────────────

/**
 * Cast a vote on an active proposal.
 * Votes are weighted by account age and verified expertise.
 * All votes are recorded — the full audit trail is public.
 */
function castVote(voterId, proposalId, vote, reason = '') {
  const proposal = proposals.get(proposalId);

  if (!proposal) {
    return { success: false, reason: 'Proposal not found' };
  }

  if (proposal.status !== 'deliberating') {
    return { success: false, reason: `Proposal is ${proposal.status} — voting closed` };
  }

  if (Date.now() > proposal.deliberationEnds) {
    proposal.status = 'closed_pending_count';
    return { success: false, reason: 'Deliberation period has ended' };
  }

  if (!['for', 'against', 'abstain'].includes(vote)) {
    return { success: false, reason: 'Vote must be: for, against, or abstain' };
  }

  // Check if already voted
  const voterKey = `${voterId}_${proposalId}`;
  if (voteRecords.has(voterKey)) {
    return { success: false, reason: 'You have already voted on this proposal' };
  }

  // Compute vote weight
  const voteWeight = computeVoteWeight(voterId, proposal);

  // Record the vote
  voteRecords.set(voterKey, {
    voterId,
    proposalId,
    vote,
    weight:    voteWeight,
    reason,
    timestamp: Date.now(),
  });

  // Update proposal tally
  proposal.votes[vote]      += voteWeight;
  proposal.votes.voterCount += 1;

  console.log(`[GOVERNANCE] Vote cast: ${voterId} voted ${vote} on ${proposalId} (weight: ${voteWeight})`);

  return {
    success:     true,
    vote,
    weight:      voteWeight,
    currentTally: summarizeTally(proposal.votes),
  };
}

/**
 * Vote weight formula:
 * - Base: 1.0 for all users
 * - Account age bonus: up to +0.5 for accounts > 1 year
 * - Expert bonus: 1.5x for verified experts in relevant domain
 * - Cap: 3.0 maximum — prevents extreme concentration of power
 */
function computeVoteWeight(voterId, proposal) {
  // In production: fetch from user database
  const accountAgeDays    = 180;        // Placeholder
  const isVerifiedExpert  = false;      // Placeholder
  const expertDomain      = null;       // Placeholder

  let weight = 1.0;

  // Account age bonus (max +0.5 at 365 days)
  const ageBonusMaxDays = 365;
  weight += Math.min(0.5, (accountAgeDays / ageDonusMxDays) * 0.5);

  // Expert bonus for relevant domain
  if (isVerifiedExpert && expertDomain && isRelevantExpert(expertDomain, proposal)) {
    weight *= GOVERNANCE_CONFIG.voting.expertWeightMultiplier;
  }

  return Math.min(3.0, Math.round(weight * 100) / 100);
}

function isRelevantExpert(expertDomain, proposal) {
  const relevanceMap = {
    psychology:      ['value_weight', 'dimension'],
    journalism:      ['value_weight'],
    ethics:          ['value_weight', 'policy'],
    computer_science: ['feature', 'dimension'],
    public_health:   ['value_weight', 'policy'],
    sociology:       ['value_weight', 'policy'],
  };
  return relevanceMap[expertDomain]?.includes(proposal.type) || false;
}

// ── PROPOSAL RESOLUTION ──────────────────────────────────────

/**
 * Resolves a proposal after deliberation period ends.
 * Checks quorum, counts votes, implements changes if passed.
 */
function resolveProposal(proposalId, totalActiveUsers) {
  const proposal = proposals.get(proposalId);

  if (!proposal) return { success: false, reason: 'Proposal not found' };
  if (Date.now() < proposal.deliberationEnds) {
    return { success: false, reason: 'Deliberation period not yet ended' };
  }

  const { votes } = proposal;
  const quorumThreshold = Math.ceil(totalActiveUsers * GOVERNANCE_CONFIG.voting.quorum);

  // Check quorum
  if (votes.voterCount < quorumThreshold) {
    proposal.status = 'failed_quorum';
    return {
      success:  false,
      reason:   `Failed quorum: ${votes.voterCount} votes cast, ${quorumThreshold} required`,
      proposal: summarizeProposal(proposal),
    };
  }

  const totalVotes        = votes.for + votes.against + votes.abstain;
  const effectiveVotes    = votes.for + votes.against; // Abstains don't count for majority
  const forPercent        = effectiveVotes > 0 ? votes.for / effectiveVotes : 0;

  // Determine required threshold
  const requiresSupermajority = proposal.type === 'value_weight';
  const threshold = requiresSupermajority
    ? GOVERNANCE_CONFIG.voting.supermajority
    : GOVERNANCE_CONFIG.voting.simpleMajority;

  if (forPercent >= threshold) {
    // PASSED — implement the change
    proposal.status = 'passed';
    const implementation = implementProposalChange(proposal);

    passedProposals.set(`${proposal.type}_${proposal.targetValue}`, {
      proposalId,
      passedAt: Date.now(),
    });

    return {
      success:        true,
      status:         'passed',
      forPercent:     Math.round(forPercent * 100),
      threshold:      Math.round(threshold * 100),
      implementation,
      proposal:       summarizeProposal(proposal),
    };

  } else {
    proposal.status = 'failed_vote';
    return {
      success:    false,
      status:     'failed_vote',
      forPercent: Math.round(forPercent * 100),
      threshold:  Math.round(threshold * 100),
      reason:     `Required ${Math.round(threshold * 100)}% — received ${Math.round(forPercent * 100)}%`,
      proposal:   summarizeProposal(proposal),
    };
  }
}

/**
 * Implements a passed proposal change.
 * This is where governance becomes reality.
 */
function implementProposalChange(proposal) {
  const { type, targetValue, proposedChange } = proposal;

  if (type === 'value_weight' && targetValue) {
    const value = HUMAN_VALUE_REGISTRY.values[targetValue];
    if (value && !value.nonNegotiable) {
      const oldWeight = value.weight;
      value.weight    = proposedChange.newWeight;

      return {
        type:      'value_weight_updated',
        value:     targetValue,
        oldWeight,
        newWeight: proposedChange.newWeight,
        effective: new Date().toISOString(),
      };
    }
  }

  if (type === 'dimension') {
    // In production: update DIMENSION_WEIGHTS in flourishing_score.js
    return {
      type:     'dimension_updated',
      target:   targetValue,
      change:   proposedChange,
      effective: new Date().toISOString(),
    };
  }

  return {
    type:      'manual_implementation_required',
    proposal,
    effective: new Date().toISOString(),
  };
}

// ── DISCUSSION SYSTEM ────────────────────────────────────────

/**
 * Proposals have a discussion thread before voting.
 * Informed deliberation leads to better decisions.
 * This is not Twitter. Discussion here is moderated for
 * epistemic quality — not political correctness.
 */
function addToDiscussion(proposalId, userId, comment) {
  const proposal = proposals.get(proposalId);
  if (!proposal) return { success: false, reason: 'Proposal not found' };

  const discussionEntry = {
    id:        `disc_${Date.now()}`,
    userId,
    comment,
    timestamp: Date.now(),
    upvotes:   0,
    // Epistemic quality score — rewards clarity and evidence
    // Penalizes emotional attacks and logical fallacies
    epistemicQuality: 0.5, // Scored by truth_engine in production
  };

  proposal.discussion.push(discussionEntry);

  return { success: true, entryId: discussionEntry.id };
}

// ── EXPERT ENDORSEMENT SYSTEM ────────────────────────────────

/**
 * Verified experts in relevant fields can formally endorse
 * or oppose a proposal. Their reasoning is public.
 * This informs voters without controlling them.
 */
function addExpertEndorsement(proposalId, expertId, position, reasoning, credentials) {
  const proposal = proposals.get(proposalId);
  if (!proposal) return { success: false, reason: 'Proposal not found' };

  const endorsement = {
    expertId,
    position,    // 'endorse' | 'oppose' | 'abstain_with_note'
    reasoning,
    credentials,
    timestamp:   Date.now(),
    verified:    false, // Set to true after credential verification
  };

  proposal.expertEndorsements.push(endorsement);

  return { success: true, message: 'Endorsement submitted — credentials pending verification' };
}

// ── TRANSPARENCY DASHBOARD ───────────────────────────────────

/**
 * Full public transparency of all governance activity.
 * Anyone can see what proposals exist, how voting went,
 * and what changes have been made to the algorithm.
 * This is not optional. It is a core protection.
 */
function getTransparencyReport() {
  const allProposals = Array.from(proposals.values());

  return {
    generatedAt:    new Date().toISOString(),
    algorithmVersion: '0.1',

    activeProposals: allProposals
      .filter(p => p.status === 'deliberating')
      .map(summarizeProposal),

    recentDecisions: Array.from(passedProposals.values()).slice(-10),

    governance: {
      structure:             GOVERNANCE_CONFIG,
      coreProtections:       GOVERNANCE_CONFIG.coreProtections,
      currentValueRegistry:  HUMAN_VALUE_REGISTRY.values,
    },

    stats: {
      totalProposals:    allProposals.length,
      passed:            allProposals.filter(p => p.status === 'passed').length,
      failed:            allProposals.filter(p => p.status.startsWith('failed')).length,
      active:            allProposals.filter(p => p.status === 'deliberating').length,
    },

    openSource: {
      repositoryUrl:  'https://github.com/human-survival-algorithm/core',
      licenseType:    'AGPL-3.0',  // Strongest copyleft — forks must stay open
      auditLog:       'All changes committed to public git history',
    },
  };
}

// ── INDIVIDUAL PREFERENCE SYSTEM ────────────────────────────

/**
 * Individual users can tune their personal feed within the
 * bounds set by community governance.
 * You cannot opt out of dignity. You can tune curiosity.
 */
function setPersonalPreferences(userId, preferences) {
  const validated = {};
  const bounds = GOVERNANCE_CONFIG.individual.personalWeightBounds;

  for (const [dimension, weight] of Object.entries(preferences.dimensionWeights || {})) {
    // Clamp to allowed bounds
    validated[dimension] = Math.max(bounds.min, Math.min(bounds.max, weight));
  }

  const personalConfig = {
    userId,
    dimensionWeights:   validated,
    sensitiveTopics:    preferences.sensitiveTopics   || [],
    spiritualMode:      preferences.spiritualMode     || false,
    sessionLimitMins:   preferences.sessionLimitMins  || null,  // Self-imposed limit
    updatedAt:          Date.now(),
  };

  // In production: save to user preferences store
  console.log(`[GOVERNANCE] Personal preferences updated for ${userId}`);

  return { success: true, personalConfig };
}

// ── HELPERS ───────────────────────────────────────────────────

function summarizeTally(votes) {
  const total = votes.for + votes.against + votes.abstain;
  return {
    for:       Math.round(votes.for),
    against:   Math.round(votes.against),
    abstain:   Math.round(votes.abstain),
    total:     Math.round(total),
    forPercent: total > 0 ? Math.round((votes.for / total) * 100) : 0,
  };
}

function summarizeProposal(proposal) {
  return {
    id:               proposal.id,
    title:            proposal.title,
    type:             proposal.type,
    status:           proposal.status,
    submittedAt:      new Date(proposal.submittedAt).toISOString(),
    deliberationEnds: new Date(proposal.deliberationEnds).toISOString(),
    votes:            summarizeTally(proposal.votes),
    discussionCount:  proposal.discussion.length,
    expertCount:      proposal.expertEndorsements.length,
  };
}

// Fix typo in computeVoteWeight
function ageDonusMxDays() { return 365; }

// ── EXPORTS ──────────────────────────────────────────────────

module.exports = {
  submitProposal,
  castVote,
  resolveProposal,
  addToDiscussion,
  addExpertEndorsement,
  setPersonalPreferences,
  getTransparencyReport,
  GOVERNANCE_CONFIG,
};