Promptgovernancesummary - Source Excerpt 01
Back to Promptgovernancesummary
Summary
This source excerpt preserves a bounded section of Spiralist/wp-content/plugins/spiralist-workspace/includes/Support/PromptGovernanceSummary.php so readers can inspect the evidence without opening the full source file.
**Source path:** Spiralist/wp-content/plugins/spiralist-workspace/includes/Support/PromptGovernanceSummary.php
<?php
namespace SpiralistWorkspace\Support;
if (!defined('ABSPATH')) {
exit;
}
/**
* Builds public and reviewer-facing moderation summaries from prompt governance signals.
*/
class PromptGovernanceSummary
{
private const ENDORSE_QUORUM = 2;
private const RESTRICT_QUORUM = 2;
private const REVERT_QUORUM = 2;
private const REPORT_QUORUM = 3;
private const STALE_REVIEW_HOURS = 72;
private const URGENT_REVIEW_HOURS = 168;
/**
* Returns the current self-operation state for one prompt.
*
* @param array<string,mixed> $prompt
* @param array<string,mixed> $review_summary
* @param array<string,mixed> $appeal_summary
* @return array<string,mixed>
*/
public static function build(array $prompt, array $review_summary = [], array $appeal_summary = []): array
{
$status = PromptMetaRegistry::normalize_moderation_status((string) ($prompt['moderation_status'] ?? 'draft'));
$lane = PromptMetaRegistry::normalize_publication_lane((string) ($prompt['publication_lane'] ?? 'community_library'));
$peer = is_array($review_summary['peer'] ?? null) ? (array) $review_summary['peer'] : [];
$quorum = [
'endorse' => self::quorum_state((int) ($peer['endorse'] ?? 0), self::ENDORSE_QUORUM),
'restrict' => self::quorum_state((int) ($peer['restrict'] ?? 0), self::RESTRICT_QUORUM),
'revert' => self::quorum_state((int) ($peer['revert'] ?? 0), self::REVERT_QUORUM),
'report' => self::quorum_state((int) ($review_summary['unique_reporters'] ?? 0), self::REPORT_QUORUM),
];
$phase = self::phase_for_status($status);
$appeals = [
'open' => (int) ($appeal_summary['open'] ?? 0),
'resolved' => (int) ($appeal_summary['resolved'] ?? 0),
'latest_status' => sanitize_key((string) ($appeal_summary['latest_status'] ?? '')),
'latest_resolution' => sanitize_key((string) ($appeal_summary['latest_resolution'] ?? '')),
'latest_resolution_utc' => (string) ($appeal_summary['latest_resolution_utc'] ?? ''),
'governance_reset_utc' => (string) ($appeal_summary['governance_reset_utc'] ?? ''),
];
$review_counts = [
'peer_reviews' => (int) ($review_summary['peer_reviews'] ?? 0),
'reports_total' => (int) ($review_summary['reports_total'] ?? 0),
'reports_from_accounts' => (int) ($review_summary['reports_from_accounts'] ?? 0),
'unique_reporters' => (int) ($review_summary['unique_reporters'] ?? 0),
];
$queue_age = self::queue_age($prompt, $status, $review_summary, $appeal_summary);
$next = self::next_action($status, $quorum, $appeals, $queue_age);
return [
'status' => $status,
'status_label' => PromptMetaRegistry::moderation_status_label($status),
'publication_lane' => $lane,
'publication_lane_label' => PromptMetaRegistry::publication_lane_label($lane),
'phase' => $phase,
'phase_label' => self::phase_label($phase),
'review_outcome' => self::review_outcome($status, $quorum),
'public_visible' => PromptMetaRegistry::is_public_moderation_status($status),
'reviewer_visible' => in_array($status, ['restricted_review', 'reverted'], true),
'machine_export_visible' => PromptMetaRegistry::is_public_moderation_status($status),
'quorum' => $quorum,
'review_counts' => $review_counts,
'appeals' => $appeals,
'queue_age' => $queue_age,
'last_review_activity_utc' => (string) ($review_summary['last_activity_utc'] ?? ''),
'last_appeal_activity_utc' => (string) ($appeal_summary['last_activity_utc'] ?? ''),
'last_activity_utc' => self::latest_timestamp(
(string) ($review_summary['last_activity_utc'] ?? ''),
(string) ($appeal_summary['last_activity_utc'] ?? '')
),
'next_action' => $next['action'],
'next_action_label' => $next['label'],
'state_note' => self::state_note($status, $phase, $next['label']),
'rules' => [
'endorse_quorum' => self::ENDORSE_QUORUM,
'restrict_quorum' => self::RESTRICT_QUORUM,
'revert_quorum' => self::REVERT_QUORUM,
'report_restriction_quorum' => self::REPORT_QUORUM,
],
];
}
/**
* Returns a quorum counter with the remaining signal count.
*
* @return array{count:int,required:int,remaining:int,met:bool}
*/
private static function quorum_state(int $count, int $required): array
{
$count = max(0, $count);
$required = max(1, $required);
return [
'count' => $count,
'required' => $required,
'remaining' => max(0, $required - $count),
'met' => $count >= $required,
];
}
/**
* Maps a moderation status to a reader-friendly phase.
*/
private static function phase_for_status(string $status): string
{
$map = [
'draft' => 'draft',
'provisional_public' => 'awaiting_review',
'peer_reviewed' => 'reviewed',
'restricted_review' => 'restricted',
'reverted' => 'reverted',
'archived' => 'archived',
'official_canon' => 'official',
];
return (string) ($map[$status] ?? 'draft');
}
/**
* Returns one phase label.
*/
private static function phase_label(string $phase): string
{
$labels = [
'draft' => 'Draft',
'awaiting_review' => 'Awaiting Review',
'reviewed' => 'Peer Reviewed',
'restricted' => 'Restricted Review',
'reverted' => 'Reverted',
'archived' => 'Archived',
'official' => 'Official',
];
return (string) ($labels[$phase] ?? $labels['draft']);
}
/**
* Returns the machine-readable outcome behind the current status.
*
* @param array<string,array<string,mixed>> $quorum
*/
private static function review_outcome(string $status, array $quorum): string
{
if ($status === 'official_canon') {
return 'official_canon';
}
if ($status === 'peer_reviewed') {
return 'peer_endorsed';
}
if ($status === 'restricted_review') {
if (!empty($quorum['report']['met'])) {
return 'restricted_by_reports';
}
return !empty($quorum['restrict']['met']) ? 'restricted_by_review' : 'restricted_by_governance';
}
if ($status === 'reverted') {
return 'reverted_by_review';
}
if ($status === 'archived') {
return 'archived';
}
if ($status === 'provisional_public') {
return 'pending_peer_review';
}
return 'not_public';
}
/**
* Returns the next useful governance action for reviewers or stewards.
*
* @param array<string,array<string,mixed>> $quorum
* @param array<string,mixed> $appeals
* @param array<string,mixed> $queue_age
* @return array{action:string,label:string}
*/
private static function next_action(string $status, array $quorum, array $appeals, array $queue_age = []): array
{
if (!empty($queue_age['is_stale'])) {
$age_label = (string) ($queue_age['duration_label'] ?? 'multiple days');
if ($status === 'provisional_public') {
return [
'action' => !empty($queue_age['is_urgent']) ? 'urgent_peer_review_needed' : 'stale_peer_review_needed',
'label' => 'No governance activity for ' . $age_label . '; reviewers should add endorsement, restriction, or reversion signal.',
];
}
if (($status === 'restricted_review' || $status === 'reverted') && (int) ($appeals['open'] ?? 0) > 0) {
return [
'action' => !empty($queue_age['is_urgent']) ? 'urgent_steward_resolution_needed' : 'stale_steward_resolution_needed',
'label' => 'Open appeal has no recent governance activity for ' . $age_label . '; stewards should resolve or request more review.',
];
}
if ($status === 'restricted_review' || $status === 'reverted') {
return [
'action' => !empty($queue_age['is_urgent']) ? 'urgent_restricted_review_needed' : 'stale_restricted_review_needed',