@holoscript/plugin-government-civic 2.0.1

package/src/__tests__/government-civic.test.ts

@@ -0,0 +1,302 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  createPermitHandler,
+  createPublicMeetingHandler,
+  createServiceRequestHandler,
+  createVotingRecordHandler,
+  createCivicComplianceHandler,
+  pluginMeta,
+  traitHandlers,
+} from '../index';
+import type { PermitConfig, PermitState } from '../traits/PermitTrait';
+import type { PublicMeetingConfig } from '../traits/PublicMeetingTrait';
+import type { ServiceRequestConfig } from '../traits/ServiceRequestTrait';
+import type { VotingRecordConfig } from '../traits/VotingRecordTrait';
+import type { CivicComplianceConfig } from '../traits/CivicComplianceTrait';
+import type { HSPlusNode, TraitContext } from '../traits/types';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeNode(): HSPlusNode { return { id: 'n1', traits: [], state: {}, position: [0, 0, 0] }; }
+function makeCtx(): TraitContext { return { emit: vi.fn(), scene: {} }; }
+
+// ── Plugin metadata ───────────────────────────────────────────────────────────
+
+describe('pluginMeta', () => {
+  it('has correct name', () => {
+    expect(pluginMeta.name).toBe('@holoscript/plugin-government-civic');
+  });
+  it('exports six traits (incl. runtime-wired civic_decision)', () => {
+    expect(pluginMeta.traits).toHaveLength(6);
+    expect(pluginMeta.traits).toContain('permit');
+    expect(pluginMeta.traits).toContain('public_meeting');
+    expect(pluginMeta.traits).toContain('service_request');
+    expect(pluginMeta.traits).toContain('voting_record');
+    expect(pluginMeta.traits).toContain('civic_compliance');
+    expect(pluginMeta.traits).toContain('civic_decision');
+  });
+  it('traitHandlers has five entries', () => {
+    expect(traitHandlers).toHaveLength(5);
+  });
+  it('each handler has required interface', () => {
+    for (const h of traitHandlers) {
+      expect(typeof h.name).toBe('string');
+      expect(h.defaultConfig).toBeDefined();
+      expect(typeof h.onAttach).toBe('function');
+      expect(typeof h.onDetach).toBe('function');
+      expect(typeof h.onEvent).toBe('function');
+    }
+  });
+});
+
+// ── PermitTrait ───────────────────────────────────────────────────────────────
+
+describe('PermitTrait', () => {
+  const cfg: PermitConfig = {
+    permitType: 'building',
+    applicationNumber: 'P-001',
+    applicantName: 'ACME Corp',
+    projectAddress: '100 Main St',
+    submittedAt: new Date(Date.now() - 86_400_000 * 5).toISOString(), // 5 days ago
+    reviewDeadlineDays: 30,
+    showStatusBadge: true,
+  };
+
+  it('initialises state on attach', () => {
+    const handler = createPermitHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    expect(node.__permitState).toBeDefined();
+    expect((node.__permitState as { daysInReview: number }).daysInReview).toBeGreaterThanOrEqual(4);
+    expect(ctx.emit).toHaveBeenCalledWith('permit:attached', expect.any(Object));
+  });
+
+  it('changes status via permit:update_status event', () => {
+    const handler = createPermitHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'permit:update_status', payload: { status: 'approved' } });
+    expect((node.__permitState as { status: string }).status).toBe('approved');
+    expect(ctx.emit).toHaveBeenCalledWith('permit:status_changed', expect.objectContaining({ to: 'approved' }));
+  });
+
+  it('cleans up on detach', () => {
+    const handler = createPermitHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onDetach(node, cfg, ctx);
+    expect(node.__permitState).toBeUndefined();
+  });
+});
+
+// ── PublicMeetingTrait ────────────────────────────────────────────────────────
+
+describe('PublicMeetingTrait', () => {
+  const cfg: PublicMeetingConfig = {
+    meetingType: 'city_council',
+    meetingId: 'CC-001',
+    title: 'April Session',
+    scheduledAt: new Date().toISOString(),
+    location: 'City Hall',
+    quorumRequired: 4,
+    membersPresent: 5,
+    publicCommentMinutesPerSpeaker: 3,
+    agenda: [
+      { id: '1', title: 'Call to Order', type: 'action', durationMinutes: 5, requiresVote: false },
+      { id: '2', title: 'Public Comment', type: 'public_comment', durationMinutes: 30, requiresVote: false },
+    ],
+    accessibilityFeatures: ['captioning'],
+  };
+
+  it('initialises with quorum met when members >= required', () => {
+    const handler = createPublicMeetingHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    expect((node.__meetingState as { quorumMet: boolean }).quorumMet).toBe(true);
+  });
+
+  it('call_to_order changes status and starts recording', () => {
+    const handler = createPublicMeetingHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'meeting:call_to_order' });
+    const s = node.__meetingState as { status: string; recordingActive: boolean };
+    expect(s.status).toBe('in_session');
+    expect(s.recordingActive).toBe(true);
+    expect(ctx.emit).toHaveBeenCalledWith('meeting:called_to_order', expect.any(Object));
+  });
+
+  it('adjourn changes status and emits event', () => {
+    const handler = createPublicMeetingHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'meeting:call_to_order' });
+    handler.onEvent(node, cfg, ctx, { type: 'meeting:adjourn' });
+    expect((node.__meetingState as { status: string }).status).toBe('adjourned');
+    expect(ctx.emit).toHaveBeenCalledWith('meeting:adjourned', expect.any(Object));
+  });
+});
+
+// ── ServiceRequestTrait ───────────────────────────────────────────────────────
+
+describe('ServiceRequestTrait', () => {
+  const cfg: ServiceRequestConfig = {
+    requestId: 'SR-001',
+    category: 'pothole',
+    description: 'Large pothole on Main St',
+    location: 'Main St & 3rd',
+    submittedAt: new Date(Date.now() - 86_400_000).toISOString(), // 1 day ago
+    priority: 'high',
+    targetResolutionDays: 3,
+    department: 'Public Works',
+    isAnonymous: false,
+  };
+
+  it('initialises state on attach', () => {
+    const handler = createServiceRequestHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    expect(node.__srState).toBeDefined();
+    expect(ctx.emit).toHaveBeenCalledWith('sr:created', expect.any(Object));
+  });
+
+  it('sr:assign sets assignedTo and status', () => {
+    const handler = createServiceRequestHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'sr:assign', payload: { assignedTo: 'crew-7' } });
+    const s = node.__srState as { status: string; assignedTo: string };
+    expect(s.status).toBe('assigned');
+    expect(s.assignedTo).toBe('crew-7');
+  });
+
+  it('sr:resolve sets status to resolved', () => {
+    const handler = createServiceRequestHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'sr:resolve' });
+    expect((node.__srState as { status: string }).status).toBe('resolved');
+    expect(ctx.emit).toHaveBeenCalledWith('sr:resolved', expect.any(Object));
+  });
+});
+
+// ── VotingRecordTrait ─────────────────────────────────────────────────────────
+
+describe('VotingRecordTrait', () => {
+  const cfg: VotingRecordConfig = {
+    voteId: 'V-001',
+    voteType: 'council_vote',
+    title: 'Budget Amendment',
+    description: 'FY2026 infrastructure spend',
+    motionText: 'Move to adopt Res 2026-19',
+    scheduledAt: new Date().toISOString(),
+    requiredMajority: 'simple',
+    eligibleVoters: ['CM-A', 'CM-B', 'CM-C', 'CM-D', 'Mayor'],
+    showLiveResults: true,
+    showMemberVotes: true,
+  };
+
+  it('initialises with pending outcome and no votes', () => {
+    const handler = createVotingRecordHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    const s = node.__votingState as { outcome: string; ayeCount: number };
+    expect(s.outcome).toBe('pending');
+    expect(s.ayeCount).toBe(0);
+  });
+
+  it('vote:cast increments aye count', () => {
+    const handler = createVotingRecordHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'vote:open' });
+    handler.onEvent(node, cfg, ctx, { type: 'vote:cast', payload: { memberId: 'CM-A', memberName: 'Councilmember A', vote: 'aye' } });
+    expect((node.__votingState as { ayeCount: number }).ayeCount).toBe(1);
+  });
+
+  it('vote:close with majority ayes resolves to passed', () => {
+    const handler = createVotingRecordHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'vote:open' });
+    for (const id of ['CM-A', 'CM-B', 'CM-C']) {
+      handler.onEvent(node, cfg, ctx, { type: 'vote:cast', payload: { memberId: id, memberName: id, vote: 'aye' } });
+    }
+    for (const id of ['CM-D', 'Mayor']) {
+      handler.onEvent(node, cfg, ctx, { type: 'vote:cast', payload: { memberId: id, memberName: id, vote: 'nay' } });
+    }
+    handler.onEvent(node, cfg, ctx, { type: 'vote:close' });
+    expect((node.__votingState as { outcome: string }).outcome).toBe('passed');
+    expect(ctx.emit).toHaveBeenCalledWith('vote:closed', expect.objectContaining({ outcome: 'passed' }));
+  });
+});
+
+// ── CivicComplianceTrait ──────────────────────────────────────────────────────
+
+describe('CivicComplianceTrait', () => {
+  const cfg: CivicComplianceConfig = {
+    entityId: 'portal-1',
+    entityType: 'website',
+    frameworks: ['ADA', 'WCAG', 'FOIA'],
+    foiaEnabled: true,
+    foiaResponseDaysLimit: 20,
+    accessibilityStandard: 'WCAG_2_1_AA',
+    auditLogRetentionDays: 2555,
+    isPublicRecord: true,
+  };
+
+  it('initialises checks for each framework', () => {
+    const handler = createCivicComplianceHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    const s = node.__complianceState as { checks: unknown[] };
+    expect(s.checks).toHaveLength(3);
+  });
+
+  it('compliance:update_check changes check status', () => {
+    const handler = createCivicComplianceHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    const s = node.__complianceState as { checks: Array<{ id: string; status: string }> };
+    const checkId = s.checks[0]!.id;
+    handler.onEvent(node, cfg, ctx, { type: 'compliance:update_check', payload: { checkId, status: 'compliant' } });
+    expect(s.checks[0]!.status).toBe('compliant');
+    expect(ctx.emit).toHaveBeenCalledWith('compliance:check_updated', expect.objectContaining({ status: 'compliant' }));
+  });
+
+  it('compliance:foia_received creates a pending FOIA request', () => {
+    const handler = createCivicComplianceHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'compliance:foia_received', payload: { requestId: 'FOIA-001', description: 'Budget docs' } });
+    const s = node.__complianceState as { foiaRequests: unknown[]; openFoiaCount: number };
+    expect(s.foiaRequests).toHaveLength(1);
+    expect(s.openFoiaCount).toBe(1);
+    expect(ctx.emit).toHaveBeenCalledWith('compliance:foia_received', expect.objectContaining({ requestId: 'FOIA-001' }));
+  });
+
+  it('audit log entry is stored', () => {
+    const handler = createCivicComplianceHandler();
+    const node = makeNode();
+    const ctx = makeCtx();
+    handler.onAttach(node, cfg, ctx);
+    handler.onEvent(node, cfg, ctx, { type: 'compliance:audit_log', payload: { action: 'page_view', actor: 'user-99', details: 'Viewed homepage' } });
+    const s = node.__complianceState as { auditLog: unknown[] };
+    expect(s.auditLog).toHaveLength(1);
+  });
+});

package/src/__tests__/runtime-integration.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Integration proof: the government-civic `civic_decision` trait, once
+ * registered via the runtime's real `registerTrait` seam, is dispatched BY THE
+ * RUNTIME and runs the deterministic TOPSIS MCDA solver — NOT called directly
+ * as a handler object.
+ *
+ * Mirrors energy-grid-plugin's runtime-integration reference (power_flow).
+ * Drives the real path: executeNode(orb) -> orb-executor -> applyDirectives ->
+ * traitHandlers.get('civic_decision').onAttach -> mcdaAnalysis.
+ * The negative control proves the registration is load-bearing (without it,
+ * the trait is a dead no-op — which is exactly the tier's status quo).
+ */
+import { describe, it, expect } from 'vitest';
+import { HoloScriptRuntime } from '@holoscript/core/runtime';
+import { registerGovernmentCivicTraitHandlers } from '../runtime';
+import type { MCDACandidate, MCDACriterion } from '../civicsolver';
+
+// One benefit criterion (weight 1.0). Two candidates: A scores 100, B scores 0.
+// normalize([100,0]) => A=1.0, B=0.0; weighted by 1.0 unchanged.
+// ideal=1.0, antiIdeal=0.0 => TOPSIS: A = 1/(0+1) = 1.0, B = 0/(1+0) = 0.0.
+// Ranked desc by TOPSIS => winner = 'A', A.rank=1, B.rank=2.
+const TWO_CANDIDATE_CRITERIA: MCDACriterion[] = [
+  { name: 'public_benefit', weight: 1.0, isBenefit: true },
+];
+const TWO_CANDIDATES: MCDACandidate[] = [
+  { id: 'A', scores: [100] },
+  { id: 'B', scores: [0] },
+];
+
+function civicDecisionOrb(config: Record<string, unknown>): unknown {
+  return {
+    type: 'orb',
+    name: 'civic',
+    properties: {},
+    methods: [],
+    position: [0, 0, 0],
+    hologram: { shape: 'orb', color: '#fff', size: 1, glow: false, interactive: false },
+    directives: [{ type: 'trait', name: 'civic_decision', config }],
+  };
+}
+
+/** Flush the runtime's async emit dispatch so `on` listeners have fired. */
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('government-civic -> HoloScript runtime integration (civic_decision)', () => {
+  it('runtime dispatch runs the TOPSIS MCDA solver for a registered @civic_decision orb', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerGovernmentCivicTraitHandlers(runtime);
+
+    const solved: Array<Record<string, unknown>> = [];
+    runtime.on('civic_decision_solved', (e: unknown) => {
+      solved.push(e as Record<string, unknown>);
+    });
+
+    await runtime.executeNode(
+      civicDecisionOrb({ candidates: TWO_CANDIDATES, criteria: TWO_CANDIDATE_CRITERIA }) as never,
+    );
+    await flush();
+
+    expect(solved).toHaveLength(1);
+    const summary = solved[0];
+    // Hand-checked: candidate A (score 100) dominates B (score 0) on the single
+    // benefit criterion, so TOPSIS makes A the winner at rank 1, B at rank 2.
+    expect(summary.winner).toBe('A');
+    expect(summary.candidateCount).toBe(2);
+    expect(summary.criterionCount).toBe(1);
+    const ranking = summary.ranking as Array<{ id: string; rank: number; topsisScore: number }>;
+    expect(ranking[0].id).toBe('A');
+    expect(ranking[0].rank).toBe(1);
+    expect(ranking[0].topsisScore).toBeCloseTo(1.0, 6);
+    expect(ranking[1].id).toBe('B');
+    expect(ranking[1].rank).toBe(2);
+    expect(ranking[1].topsisScore).toBeCloseTo(0.0, 6);
+  });
+
+  it('NEGATIVE CONTROL: without registration the @civic_decision trait is a dead no-op', async () => {
+    const runtime = new HoloScriptRuntime(); // intentionally NOT registered
+    const solved: unknown[] = [];
+    runtime.on('civic_decision_solved', (e: unknown) => solved.push(e));
+
+    await runtime.executeNode(
+      civicDecisionOrb({ candidates: TWO_CANDIDATES, criteria: TWO_CANDIDATE_CRITERIA }) as never,
+    );
+    await flush();
+
+    expect(solved).toHaveLength(0);
+  });
+
+  it('persists the solver result into durable runtime state on ATTACH', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerGovernmentCivicTraitHandlers(runtime);
+
+    await runtime.executeNode(
+      civicDecisionOrb({ candidates: TWO_CANDIDATES, criteria: TWO_CANDIDATE_CRITERIA }) as never,
+    );
+    await flush();
+
+    const state = runtime.getState() as Record<string, unknown>;
+    const persisted = state['civic_decision:civic'] as
+      | { winner?: string; candidateCount?: number }
+      | undefined;
+    expect(persisted).toBeDefined();
+    expect(persisted?.winner).toBe('A');
+    expect(persisted?.candidateCount).toBe(2);
+  });
+
+  it('emits civic_decision_error (does not throw through the runtime) for invalid config', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerGovernmentCivicTraitHandlers(runtime);
+
+    const errors: Array<Record<string, unknown>> = [];
+    runtime.on('civic_decision_error', (e: unknown) => {
+      errors.push(e as Record<string, unknown>);
+    });
+
+    // candidate scores length (2) does not match criteria length (1) — the real
+    // solver throws "scores.length must match criteria.length", which the
+    // handler's try/catch turns into a civic_decision_error rather than a throw.
+    const mismatched: MCDACandidate[] = [{ id: 'A', scores: [1, 2] }];
+    await runtime.executeNode(
+      civicDecisionOrb({ candidates: mismatched, criteria: TWO_CANDIDATE_CRITERIA }) as never,
+    );
+    await flush();
+
+    expect(errors).toHaveLength(1);
+    expect(String(errors[0].error)).toContain('match');
+  });
+});