@holoscript/plugin-government-civic 2.0.1

package/src/traits/CivicComplianceTrait.ts

@@ -0,0 +1,165 @@
+/** @civic_compliance Trait — ADA, FOIA, and public records compliance enforcement. @trait civic_compliance */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ComplianceFramework = 'ADA' | 'FOIA' | 'WCAG' | 'OPRA' | 'GDPR' | 'CCPA' | 'section508';
+export type ComplianceStatus = 'compliant' | 'non_compliant' | 'pending_review' | 'exempt' | 'remediation_in_progress';
+
+export interface ComplianceCheck {
+  id: string;
+  framework: ComplianceFramework;
+  requirement: string;
+  status: ComplianceStatus;
+  lastChecked: string;
+  remediation?: string;
+  dueDate?: string;
+}
+
+export interface FoiaRequest {
+  requestId: string;
+  requestedAt: string;
+  description: string;
+  status: 'received' | 'processing' | 'fulfilled' | 'denied' | 'appealed';
+  responseDueAt: string; // 20 business days under US federal FOIA
+}
+
+export interface CivicComplianceConfig {
+  entityId: string;
+  entityType: 'website' | 'facility' | 'service' | 'document' | 'meeting';
+  frameworks: ComplianceFramework[];
+  foiaEnabled: boolean;
+  foiaResponseDaysLimit: number; // default 20 federal, varies by state
+  accessibilityStandard: 'WCAG_2_1_AA' | 'WCAG_2_1_AAA' | 'WCAG_2_2_AA' | 'section508';
+  auditLogRetentionDays: number;
+  isPublicRecord: boolean;
+}
+
+export interface CivicComplianceState {
+  overallStatus: ComplianceStatus;
+  checks: ComplianceCheck[];
+  foiaRequests: FoiaRequest[];
+  auditLog: Array<{ timestamp: string; action: string; actor: string; details: string }>;
+  lastAuditAt: string;
+  openFoiaCount: number;
+  overdueFoiaCount: number;
+  nonCompliantCount: number;
+}
+
+const defaultConfig: CivicComplianceConfig = {
+  entityId: '',
+  entityType: 'service',
+  frameworks: ['ADA', 'FOIA', 'WCAG'],
+  foiaEnabled: true,
+  foiaResponseDaysLimit: 20,
+  accessibilityStandard: 'WCAG_2_1_AA',
+  auditLogRetentionDays: 2555, // 7 years
+  isPublicRecord: true,
+};
+
+function computeOverallStatus(checks: ComplianceCheck[]): ComplianceStatus {
+  if (checks.some(c => c.status === 'non_compliant')) return 'non_compliant';
+  if (checks.some(c => c.status === 'remediation_in_progress')) return 'remediation_in_progress';
+  if (checks.some(c => c.status === 'pending_review')) return 'pending_review';
+  if (checks.length > 0 && checks.every(c => c.status === 'compliant' || c.status === 'exempt')) return 'compliant';
+  return 'pending_review';
+}
+
+export function createCivicComplianceHandler(): TraitHandler<CivicComplianceConfig> {
+  return {
+    name: 'civic_compliance',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: CivicComplianceConfig, ctx: TraitContext) {
+      // Seed initial checks based on declared frameworks
+      const checks: ComplianceCheck[] = config.frameworks.map(fw => ({
+        id: `${config.entityId}-${fw.toLowerCase()}`,
+        framework: fw,
+        requirement: `${fw} baseline compliance`,
+        status: 'pending_review' as ComplianceStatus,
+        lastChecked: new Date().toISOString(),
+      }));
+      node.__complianceState = {
+        overallStatus: 'pending_review' as ComplianceStatus,
+        checks,
+        foiaRequests: [],
+        auditLog: [],
+        lastAuditAt: new Date().toISOString(),
+        openFoiaCount: 0,
+        overdueFoiaCount: 0,
+        nonCompliantCount: 0,
+      } satisfies CivicComplianceState;
+      ctx.emit?.('compliance:initialized', { entityId: config.entityId, frameworks: config.frameworks });
+    },
+    onDetach(node: HSPlusNode, _config: CivicComplianceConfig, ctx: TraitContext) {
+      delete node.__complianceState;
+      ctx.emit?.('compliance:removed');
+    },
+    onUpdate(node: HSPlusNode, config: CivicComplianceConfig, ctx: TraitContext, _delta: number) {
+      const s = node.__complianceState as CivicComplianceState | undefined;
+      if (!s) return;
+      const now = Date.now();
+      // Check FOIA deadlines
+      let overdue = 0;
+      for (const req of s.foiaRequests) {
+        if (req.status === 'received' || req.status === 'processing') {
+          const dueAt = new Date(req.responseDueAt).getTime();
+          if (now > dueAt) overdue++;
+        }
+      }
+      const prevOverdue = s.overdueFoiaCount;
+      s.overdueFoiaCount = overdue;
+      if (overdue > prevOverdue) {
+        ctx.emit?.('compliance:foia_overdue', { entityId: config.entityId, overdueCount: overdue });
+      }
+      s.openFoiaCount = s.foiaRequests.filter(r => r.status === 'received' || r.status === 'processing').length;
+      s.nonCompliantCount = s.checks.filter(c => c.status === 'non_compliant').length;
+      s.overallStatus = computeOverallStatus(s.checks);
+    },
+    onEvent(node: HSPlusNode, config: CivicComplianceConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__complianceState as CivicComplianceState | undefined;
+      if (!s) return;
+      switch (event.type) {
+        case 'compliance:update_check': {
+          const { checkId, status, remediation } = event.payload as { checkId: string; status: ComplianceStatus; remediation?: string };
+          const check = s.checks.find(c => c.id === checkId);
+          if (check) {
+            check.status = status;
+            check.lastChecked = new Date().toISOString();
+            if (remediation) check.remediation = remediation;
+            s.overallStatus = computeOverallStatus(s.checks);
+            ctx.emit?.('compliance:check_updated', { checkId, status, overall: s.overallStatus });
+          }
+          break;
+        }
+        case 'compliance:foia_received': {
+          if (!config.foiaEnabled) return;
+          const req = event.payload as unknown as FoiaRequest;
+          if (!req?.requestId) return;
+          const receivedAt = new Date();
+          // Approx 20 business days = 28 calendar days
+          const dueAt = new Date(receivedAt.getTime() + config.foiaResponseDaysLimit * 1.4 * 86_400_000);
+          s.foiaRequests.push({ ...req, requestedAt: receivedAt.toISOString(), responseDueAt: dueAt.toISOString(), status: 'received' });
+          s.openFoiaCount = s.foiaRequests.filter(r => r.status === 'received' || r.status === 'processing').length;
+          ctx.emit?.('compliance:foia_received', { requestId: req.requestId, dueAt: dueAt.toISOString() });
+          break;
+        }
+        case 'compliance:foia_fulfill': {
+          const requestId = event.payload?.requestId as string;
+          const req = s.foiaRequests.find(r => r.requestId === requestId);
+          if (req) {
+            req.status = 'fulfilled';
+            s.openFoiaCount = s.foiaRequests.filter(r => r.status === 'received' || r.status === 'processing').length;
+            ctx.emit?.('compliance:foia_fulfilled', { requestId });
+          }
+          break;
+        }
+        case 'compliance:audit_log': {
+          const { action, actor, details } = event.payload as { action: string; actor: string; details: string };
+          s.auditLog.push({ timestamp: new Date().toISOString(), action, actor, details: details ?? '' });
+          // Prune logs older than retention window
+          const cutoff = Date.now() - config.auditLogRetentionDays * 86_400_000;
+          s.auditLog = s.auditLog.filter(e => new Date(e.timestamp).getTime() > cutoff);
+          break;
+        }
+      }
+    },
+  };
+}

package/src/traits/PermitTrait.ts

@@ -0,0 +1,107 @@
+/** @permit Trait — Building and business permit lifecycle management. @trait permit */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type PermitType = 'building' | 'business' | 'event' | 'demolition' | 'electrical' | 'plumbing' | 'sign' | 'zoning';
+export type PermitStatus = 'submitted' | 'under_review' | 'approved' | 'denied' | 'expired' | 'revoked' | 'withdrawn';
+
+export interface PermitConfig {
+  permitType: PermitType;
+  applicationNumber: string;
+  applicantName: string;
+  projectAddress: string;
+  submittedAt: string; // ISO date
+  expiresAt?: string;  // ISO date — when approved permit expires
+  reviewDeadlineDays: number;
+  showStatusBadge: boolean;
+}
+
+export interface PermitState {
+  status: PermitStatus;
+  applicationNumber: string;
+  daysInReview: number;
+  isOverdue: boolean;
+  isExpiringSoon: boolean; // within 30 days
+  isExpired: boolean;
+  reviewNotes: string[];
+  lastUpdated: string;
+}
+
+const defaultConfig: PermitConfig = {
+  permitType: 'building',
+  applicationNumber: '',
+  applicantName: '',
+  projectAddress: '',
+  submittedAt: new Date().toISOString(),
+  reviewDeadlineDays: 30,
+  showStatusBadge: true,
+};
+
+function computeState(config: PermitConfig, existing?: Partial<PermitState>): PermitState {
+  const now = Date.now();
+  const submitted = new Date(config.submittedAt).getTime();
+  const daysInReview = Math.floor((now - submitted) / 86_400_000);
+  const expiresAt = config.expiresAt ? new Date(config.expiresAt).getTime() : null;
+  const daysUntilExpiry = expiresAt ? Math.floor((expiresAt - now) / 86_400_000) : null;
+
+  return {
+    status: (existing?.status as PermitStatus) ?? 'submitted',
+    applicationNumber: config.applicationNumber,
+    daysInReview,
+    isOverdue: daysInReview > config.reviewDeadlineDays,
+    isExpiringSoon: daysUntilExpiry !== null && daysUntilExpiry >= 0 && daysUntilExpiry <= 30,
+    isExpired: daysUntilExpiry !== null && daysUntilExpiry < 0,
+    reviewNotes: (existing?.reviewNotes as string[]) ?? [],
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+export function createPermitHandler(): TraitHandler<PermitConfig> {
+  return {
+    name: 'permit',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: PermitConfig, ctx: TraitContext) {
+      node.__permitState = computeState(config);
+      ctx.emit?.('permit:attached', {
+        applicationNumber: config.applicationNumber,
+        type: config.permitType,
+      });
+    },
+    onDetach(node: HSPlusNode, _config: PermitConfig, ctx: TraitContext) {
+      delete node.__permitState;
+      ctx.emit?.('permit:detached');
+    },
+    onUpdate(node: HSPlusNode, config: PermitConfig, ctx: TraitContext, _delta: number) {
+      const prev = node.__permitState as PermitState | undefined;
+      const next = computeState(config, prev);
+      if (next.isOverdue && !prev?.isOverdue) {
+        ctx.emit?.('permit:overdue', { applicationNumber: config.applicationNumber, daysInReview: next.daysInReview });
+      }
+      if (next.isExpiringSoon && !prev?.isExpiringSoon) {
+        ctx.emit?.('permit:expiring_soon', { applicationNumber: config.applicationNumber });
+      }
+      if (next.isExpired && !prev?.isExpired) {
+        ctx.emit?.('permit:expired', { applicationNumber: config.applicationNumber });
+      }
+      node.__permitState = next;
+    },
+    onEvent(node: HSPlusNode, config: PermitConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__permitState as PermitState | undefined;
+      if (!s) return;
+      if (event.type === 'permit:update_status') {
+        const newStatus = event.payload?.status as PermitStatus;
+        if (!newStatus) return;
+        const prev = s.status;
+        s.status = newStatus;
+        s.lastUpdated = new Date().toISOString();
+        ctx.emit?.('permit:status_changed', { from: prev, to: newStatus, applicationNumber: config.applicationNumber });
+      }
+      if (event.type === 'permit:add_note') {
+        const note = event.payload?.note as string;
+        if (note) {
+          s.reviewNotes.push(note);
+          ctx.emit?.('permit:note_added', { applicationNumber: config.applicationNumber, noteCount: s.reviewNotes.length });
+        }
+      }
+    },
+  };
+}

package/src/traits/PublicMeetingTrait.ts

@@ -0,0 +1,123 @@
+/** @public_meeting Trait — City council and public hearing management. @trait public_meeting */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type MeetingType = 'city_council' | 'planning_commission' | 'public_hearing' | 'zoning_board' | 'budget_session' | 'town_hall';
+export type MeetingStatus = 'scheduled' | 'in_session' | 'recess' | 'public_comment' | 'voting' | 'adjourned' | 'cancelled';
+
+export interface AgendaItem {
+  id: string;
+  title: string;
+  type: 'presentation' | 'discussion' | 'action' | 'public_comment' | 'vote';
+  durationMinutes: number;
+  requiresVote: boolean;
+}
+
+export interface PublicMeetingConfig {
+  meetingType: MeetingType;
+  meetingId: string;
+  title: string;
+  scheduledAt: string; // ISO datetime
+  location: string;
+  quorumRequired: number;
+  membersPresent: number;
+  publicCommentMinutesPerSpeaker: number;
+  agenda: AgendaItem[];
+  streamUrl?: string;
+  accessibilityFeatures: string[]; // e.g. ['captioning', 'sign_language', 'hearing_loop']
+}
+
+export interface PublicMeetingState {
+  status: MeetingStatus;
+  quorumMet: boolean;
+  currentAgendaItemIndex: number;
+  publicSpeakersRegistered: number;
+  publicSpeakersHeard: number;
+  minutesElapsed: number;
+  recordingActive: boolean;
+  lastUpdated: string;
+}
+
+const defaultConfig: PublicMeetingConfig = {
+  meetingType: 'city_council',
+  meetingId: '',
+  title: '',
+  scheduledAt: new Date().toISOString(),
+  location: '',
+  quorumRequired: 4,
+  membersPresent: 0,
+  publicCommentMinutesPerSpeaker: 3,
+  agenda: [],
+  accessibilityFeatures: ['captioning'],
+};
+
+export function createPublicMeetingHandler(): TraitHandler<PublicMeetingConfig> {
+  return {
+    name: 'public_meeting',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: PublicMeetingConfig, ctx: TraitContext) {
+      node.__meetingState = {
+        status: 'scheduled' as MeetingStatus,
+        quorumMet: config.membersPresent >= config.quorumRequired,
+        currentAgendaItemIndex: 0,
+        publicSpeakersRegistered: 0,
+        publicSpeakersHeard: 0,
+        minutesElapsed: 0,
+        recordingActive: false,
+        lastUpdated: new Date().toISOString(),
+      } satisfies PublicMeetingState;
+      ctx.emit?.('meeting:scheduled', { meetingId: config.meetingId, type: config.meetingType });
+    },
+    onDetach(node: HSPlusNode, _config: PublicMeetingConfig, ctx: TraitContext) {
+      delete node.__meetingState;
+      ctx.emit?.('meeting:removed');
+    },
+    onUpdate(node: HSPlusNode, config: PublicMeetingConfig, ctx: TraitContext, delta: number) {
+      const s = node.__meetingState as PublicMeetingState | undefined;
+      if (!s) return;
+      if (s.status === 'in_session' || s.status === 'public_comment') {
+        s.minutesElapsed += delta / 60; // delta in seconds
+      }
+      const quorumMet = config.membersPresent >= config.quorumRequired;
+      if (quorumMet !== s.quorumMet) {
+        s.quorumMet = quorumMet;
+        ctx.emit?.(quorumMet ? 'meeting:quorum_met' : 'meeting:quorum_lost', { meetingId: config.meetingId });
+      }
+      s.lastUpdated = new Date().toISOString();
+    },
+    onEvent(node: HSPlusNode, config: PublicMeetingConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__meetingState as PublicMeetingState | undefined;
+      if (!s) return;
+      switch (event.type) {
+        case 'meeting:call_to_order':
+          s.status = 'in_session';
+          s.recordingActive = true;
+          ctx.emit?.('meeting:called_to_order', { meetingId: config.meetingId, quorumMet: s.quorumMet });
+          break;
+        case 'meeting:open_public_comment':
+          s.status = 'public_comment';
+          ctx.emit?.('meeting:public_comment_open', { speakersRegistered: s.publicSpeakersRegistered });
+          break;
+        case 'meeting:register_speaker':
+          s.publicSpeakersRegistered++;
+          ctx.emit?.('meeting:speaker_registered', { total: s.publicSpeakersRegistered });
+          break;
+        case 'meeting:next_speaker':
+          s.publicSpeakersHeard++;
+          ctx.emit?.('meeting:speaker_started', { heard: s.publicSpeakersHeard, remaining: s.publicSpeakersRegistered - s.publicSpeakersHeard });
+          break;
+        case 'meeting:next_agenda_item':
+          if (s.currentAgendaItemIndex < config.agenda.length - 1) {
+            s.currentAgendaItemIndex++;
+            const item = config.agenda[s.currentAgendaItemIndex];
+            ctx.emit?.('meeting:agenda_advanced', { index: s.currentAgendaItemIndex, item: item?.title });
+          }
+          break;
+        case 'meeting:adjourn':
+          s.status = 'adjourned';
+          s.recordingActive = false;
+          ctx.emit?.('meeting:adjourned', { meetingId: config.meetingId, minutesElapsed: Math.round(s.minutesElapsed) });
+          break;
+      }
+    },
+  };
+}

package/src/traits/ServiceRequestTrait.ts

@@ -0,0 +1,124 @@
+/** @service_request Trait — 311-style civic service request tracking. @trait service_request */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ServiceCategory = 'pothole' | 'streetlight' | 'graffiti' | 'abandoned_vehicle' | 'code_violation' | 'tree_hazard' | 'water_main' | 'sidewalk' | 'noise_complaint' | 'other';
+export type RequestStatus = 'submitted' | 'acknowledged' | 'assigned' | 'in_progress' | 'resolved' | 'closed' | 'duplicate';
+export type PriorityLevel = 'low' | 'medium' | 'high' | 'urgent';
+
+export interface ServiceRequestConfig {
+  requestId: string;
+  category: ServiceCategory;
+  description: string;
+  location: string;
+  coordinates?: { lat: number; lng: number };
+  submittedAt: string;  // ISO datetime
+  priority: PriorityLevel;
+  targetResolutionDays: number; // SLA days by priority
+  department: string;
+  contactEmail?: string;
+  isAnonymous: boolean;
+}
+
+export interface ServiceRequestState {
+  status: RequestStatus;
+  requestId: string;
+  assignedTo?: string;
+  daysOpen: number;
+  isSlaBreached: boolean;
+  lastStatusChange: string;
+  updates: Array<{ timestamp: string; message: string; author: string }>;
+}
+
+const SLA_DAYS: Record<PriorityLevel, number> = {
+  urgent: 1,
+  high: 3,
+  medium: 7,
+  low: 14,
+};
+
+const defaultConfig: ServiceRequestConfig = {
+  requestId: '',
+  category: 'other',
+  description: '',
+  location: '',
+  submittedAt: new Date().toISOString(),
+  priority: 'medium',
+  targetResolutionDays: SLA_DAYS.medium,
+  department: 'Public Works',
+  isAnonymous: false,
+};
+
+export function createServiceRequestHandler(): TraitHandler<ServiceRequestConfig> {
+  return {
+    name: 'service_request',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: ServiceRequestConfig, ctx: TraitContext) {
+      const now = Date.now();
+      const submitted = new Date(config.submittedAt).getTime();
+      const daysOpen = Math.floor((now - submitted) / 86_400_000);
+      const slaLimit = config.targetResolutionDays || SLA_DAYS[config.priority];
+
+      node.__srState = {
+        status: 'submitted' as RequestStatus,
+        requestId: config.requestId,
+        daysOpen,
+        isSlaBreached: daysOpen > slaLimit,
+        lastStatusChange: config.submittedAt,
+        updates: [],
+      } satisfies ServiceRequestState;
+
+      ctx.emit?.('sr:created', { requestId: config.requestId, category: config.category });
+    },
+    onDetach(node: HSPlusNode, _config: ServiceRequestConfig, ctx: TraitContext) {
+      delete node.__srState;
+      ctx.emit?.('sr:removed');
+    },
+    onUpdate(node: HSPlusNode, config: ServiceRequestConfig, _ctx: TraitContext, _delta: number) {
+      const s = node.__srState as ServiceRequestState | undefined;
+      if (!s) return;
+      const now = Date.now();
+      const submitted = new Date(config.submittedAt).getTime();
+      s.daysOpen = Math.floor((now - submitted) / 86_400_000);
+      const slaLimit = config.targetResolutionDays || SLA_DAYS[config.priority];
+      s.isSlaBreached = s.daysOpen > slaLimit && s.status !== 'resolved' && s.status !== 'closed';
+    },
+    onEvent(node: HSPlusNode, config: ServiceRequestConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__srState as ServiceRequestState | undefined;
+      if (!s) return;
+      switch (event.type) {
+        case 'sr:assign': {
+          const assignedTo = event.payload?.assignedTo as string;
+          s.assignedTo = assignedTo;
+          s.status = 'assigned';
+          s.lastStatusChange = new Date().toISOString();
+          ctx.emit?.('sr:assigned', { requestId: config.requestId, assignedTo });
+          break;
+        }
+        case 'sr:update_status': {
+          const newStatus = event.payload?.status as RequestStatus;
+          if (!newStatus) return;
+          const prev = s.status;
+          s.status = newStatus;
+          s.lastStatusChange = new Date().toISOString();
+          ctx.emit?.('sr:status_changed', { from: prev, to: newStatus, requestId: config.requestId });
+          break;
+        }
+        case 'sr:add_update': {
+          const message = event.payload?.message as string;
+          const author = (event.payload?.author as string) ?? 'staff';
+          if (message) {
+            s.updates.push({ timestamp: new Date().toISOString(), message, author });
+            ctx.emit?.('sr:update_added', { requestId: config.requestId, updateCount: s.updates.length });
+          }
+          break;
+        }
+        case 'sr:resolve': {
+          s.status = 'resolved';
+          s.lastStatusChange = new Date().toISOString();
+          ctx.emit?.('sr:resolved', { requestId: config.requestId, daysOpen: s.daysOpen });
+          break;
+        }
+      }
+    },
+  };
+}

package/src/traits/VotingRecordTrait.ts

@@ -0,0 +1,128 @@
+/** @voting_record Trait — Public voting record and election results display. @trait voting_record */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type VoteType = 'council_vote' | 'ballot_measure' | 'election' | 'referendum' | 'committee_vote';
+export type VoteOutcome = 'passed' | 'failed' | 'tabled' | 'withdrawn' | 'tied' | 'pending';
+
+export interface VoteCast {
+  memberId: string;
+  memberName: string;
+  vote: 'aye' | 'nay' | 'abstain' | 'absent';
+  timestamp?: string;
+}
+
+export interface VotingRecordConfig {
+  voteId: string;
+  voteType: VoteType;
+  title: string;
+  description: string;
+  motionText: string;
+  scheduledAt: string; // ISO datetime
+  requiredMajority: 'simple' | 'supermajority' | 'unanimous'; // simple=50%+1, supermajority=2/3, unanimous=100%
+  eligibleVoters: string[]; // member IDs
+  showLiveResults: boolean;
+  showMemberVotes: boolean; // public record
+}
+
+export interface VotingRecordState {
+  outcome: VoteOutcome;
+  votes: VoteCast[];
+  ayeCount: number;
+  nayCount: number;
+  abstainCount: number;
+  absentCount: number;
+  totalEligible: number;
+  participationRate: number; // 0-1
+  quorumMet: boolean;
+  isOpen: boolean;
+  closedAt?: string;
+}
+
+const MAJORITY_THRESHOLDS = { simple: 0.5, supermajority: 2 / 3, unanimous: 1 } as const;
+
+function computeOutcome(state: VotingRecordState, config: VotingRecordConfig): VoteOutcome {
+  if (state.isOpen) return 'pending';
+  const total = state.ayeCount + state.nayCount + state.abstainCount;
+  if (total === 0) return 'pending';
+  const threshold = MAJORITY_THRESHOLDS[config.requiredMajority];
+  const ayeRatio = state.ayeCount / total;
+  if (state.ayeCount === state.nayCount) return 'tied';
+  return ayeRatio > threshold ? 'passed' : 'failed';
+}
+
+const defaultConfig: VotingRecordConfig = {
+  voteId: '',
+  voteType: 'council_vote',
+  title: '',
+  description: '',
+  motionText: '',
+  scheduledAt: new Date().toISOString(),
+  requiredMajority: 'simple',
+  eligibleVoters: [],
+  showLiveResults: true,
+  showMemberVotes: true,
+};
+
+export function createVotingRecordHandler(): TraitHandler<VotingRecordConfig> {
+  return {
+    name: 'voting_record',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: VotingRecordConfig, ctx: TraitContext) {
+      node.__votingState = {
+        outcome: 'pending' as VoteOutcome,
+        votes: [],
+        ayeCount: 0, nayCount: 0, abstainCount: 0,
+        absentCount: config.eligibleVoters.length,
+        totalEligible: config.eligibleVoters.length,
+        participationRate: 0,
+        quorumMet: false,
+        isOpen: false,
+      } satisfies VotingRecordState;
+      ctx.emit?.('vote:created', { voteId: config.voteId, type: config.voteType });
+    },
+    onDetach(node: HSPlusNode, _config: VotingRecordConfig, ctx: TraitContext) {
+      delete node.__votingState;
+      ctx.emit?.('vote:removed');
+    },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, config: VotingRecordConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__votingState as VotingRecordState | undefined;
+      if (!s) return;
+      switch (event.type) {
+        case 'vote:open':
+          s.isOpen = true;
+          ctx.emit?.('vote:opened', { voteId: config.voteId, eligible: s.totalEligible });
+          break;
+        case 'vote:cast': {
+          if (!s.isOpen) return;
+          const cast = event.payload as unknown as VoteCast;
+          if (!cast?.memberId || !cast?.vote) return;
+          // Replace if already voted
+          const existing = s.votes.findIndex(v => v.memberId === cast.memberId);
+          if (existing >= 0) s.votes.splice(existing, 1);
+          s.votes.push({ ...cast, timestamp: new Date().toISOString() });
+          // Recount
+          s.ayeCount = s.votes.filter(v => v.vote === 'aye').length;
+          s.nayCount = s.votes.filter(v => v.vote === 'nay').length;
+          s.abstainCount = s.votes.filter(v => v.vote === 'abstain').length;
+          s.absentCount = s.totalEligible - s.votes.length;
+          s.participationRate = s.votes.length / (s.totalEligible || 1);
+          s.quorumMet = s.participationRate > 0.5;
+          ctx.emit?.('vote:cast', { voteId: config.voteId, memberId: cast.memberId, vote: cast.vote, ayeCount: s.ayeCount, nayCount: s.nayCount });
+          break;
+        }
+        case 'vote:close':
+          s.isOpen = false;
+          s.closedAt = new Date().toISOString();
+          s.outcome = computeOutcome(s, config);
+          ctx.emit?.('vote:closed', { voteId: config.voteId, outcome: s.outcome, ayeCount: s.ayeCount, nayCount: s.nayCount });
+          break;
+        case 'vote:table':
+          s.isOpen = false;
+          s.outcome = 'tabled';
+          ctx.emit?.('vote:tabled', { voteId: config.voteId });
+          break;
+      }
+    },
+  };
+}

package/src/traits/types.ts

@@ -0,0 +1,4 @@
+export interface HSPlusNode { id?: string; properties?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitContext { emit?: (event: string, payload?: unknown) => void; getState?: () => Record<string, unknown>; setState?: (updates: Record<string, unknown>) => void; [key: string]: unknown; }
+export interface TraitEvent { type: string; source?: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitHandler<TConfig = unknown> { name: string; defaultConfig: TConfig; onAttach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onDetach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onUpdate(node: HSPlusNode, config: TConfig, ctx: TraitContext, delta: number): void; onEvent(node: HSPlusNode, config: TConfig, ctx: TraitContext, event: TraitEvent): void; }

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../../tsconfig.json", "compilerOptions": { "outDir": "dist", "rootDir": "src", "declaration": true, "declarationMap": true }, "include": ["src"] }

package/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+// resolve.alias is REQUIRED: without it, `@holoscript/core/runtime` resolves to
+// the STALE built dist and registerPluginTraits is missing ("not a function").
+// Point the subpath imports at core/engine source so the runtime barrel
+// (core/src/runtime.ts) and shared registrar resolve from source. Mirrors
+// energy-grid-plugin/vitest.config.ts.
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@holoscript/engine': resolve(__dirname, '../../engine/src'),
+      '@holoscript/core': resolve(__dirname, '../../core/src'),
+    },
+  },
+  test: { globals: true },
+});