CCGSC Operator & System Manual

1. What CCGSC Is

The Cluster Computing Grid System (CCGSC) is a distributed, heterogeneous grid computing framework designed to orchestrate browser worker tabs and edge nodes executing WebAssembly (WASM) and high-performance JavaScript workloads. The system partitions extensive numerical search spaces and dense matrix operations across concurrent worker clients, coordinating task assignment, lease lifecycle management, result validation, and audit trail preservation without requiring client-side installations.

CCGSC implements three distinct computational pipelines, termed lanes:

1. IsPrime Lane: A distributed prime candidate search engine utilizing Miller-Rabin and trial division algorithms coordinated via persistent bidirectional WebSockets.
2. SSPrime Lane: A high-throughput segmented sieve of Eratosthenes pipeline coordinated via lightweight HTTP REST leasing endpoints.
3. Matrix Lane: A distributed block-matrix multiplication system (WASM ABI V2) featuring cryptographic hash verification, task leasing, and an immutable hash-chained audit (HCIA) log.

Node coordination and cluster state are synchronized across Node.js backend processes, Fastify HTTP microservices, Redis persistence keys, and PM2 process management, ensuring fault tolerance, automatic failover, and zero feature loss during computational runs.

2. Architecture & Computational Lanes

The platform separates operational responsibilities into independent server daemons and client-facing dashboards:

• Root Coordinator Service (coordinator_server.js): Manages WebSocket connectivity for the IsPrime lane, maintains the in-memory task queue, registers connected workers, executes periodic state saves to config/isprime_config.v1.json, and writes timestamped archives into archive/isprime/<timestamp>/.
• Admin & Pool Server (server/admin_server.js): Fastify-based HTTP application hosting the SSPrime routes (server/routes/prime.js), Matrix routes (server/routes/matrix.js), Worker Pool administration (server/routes/pool_admin.js), and Session Authentication.
• Worker Gateway (server/pool_gateway.js): Redis-backed registration and heartbeat aggregator managing worker liveness TTLs, cluster tagging, and lane policy dispatch.
• Persistence Layer: Redis stores operational liveness and cluster dispatch keys, while durable file-backed storage preserves JSON configuration defaults, run checkpoints, task logs (task_log.csv), and append-only audit segments.

3. IsPrime Director (public/director.html)

The IsPrime Director interface monitors and commands the WebSocket-based prime distribution coordinator. It allows operators to configure search limits, partition work units into discrete tasks, initiate distributed runs, monitor real-time worker progress, and archive run evidence.

Section Order & Normal Appearance

1. Auth Bar: Displays session identity and the logout-btn control. Normal status shows authenticated role (director, admin, or owner).
2. Dashboard & Controls: Displays primary computation status (Idle, Running, or Paused), upper limit N, active worker counts, and legacy control buttons. The clearStateBtn remains in the visible row; legacy buttons (start-btn, pause-resume-btn, restart-btn) are housed in a collapsed details box.
3. Overall Progress: Real-time progress bar reflecting task completion ratio, total primes found, and elapsed time.
4. Worker Management: Live table of coordinator-connected WebSocket workers, reporting Device ID, Tab ID, IP address, currently leased task range, completed tasks, primes discovered, CPU concurrency, browser profile, and memory footprint. Per-row eviction is provided via inline termination buttons.
5. Pool Workers Panel: Mounts the shared pool observer displaying generic worker tabs and multi-lane workers.
6. Sitemap / Navigation: Direct navigation links across all operator, monitor, and manual pages.
7. Ops, Analytics & WorkerStats: Diagnostic links and the rebuild-worker-stats-btn button.
8. Worker Entry Points / Test Lanes: Operational URLs for public contributors, standalone prime workers, proof-mode tabs, and Matrix workers. Includes legacy launcher start-seg-btn.
9. IsPrime Operator Configuration & Controls (wo6-ip-*): The primary visible operator surface for setting parameters, staging changes, controlling execution, refreshing status, and executing archives.
10. Cluster Dispatch Control: Mounted by control_renderer.js; provides clust-apply-isprime to enforce cluster routing.
11. Shared Persistence Panel: Mounts persistence_panel.js to monitor storage health and snapshot intervals.
12. Audit Log & Rotation Card: Displays active segment metrics, automatic midnight rotation status, and controls h7-audit-refresh and h7-audit-rotate.

Configuration Inputs

• Upper Limit (N) (wo6-ip-N): Inclusive upper bound of the prime search space (must be integer ≥ 2).
• Task Count (wo6-ip-tasks): Total number of discrete partition ranges to generate across the search space.
• Task Count AUTO (wo6-ip-auto): Checkbox enabling the coordinator to automatically compute an optimal task partition count based on N.

Controls Reference — IsPrime Director

4. SSPrime Director (public/ssp_director.html)

The SSPrime Director drives the HTTP segmented-sieve computational lane hosted by the Fastify admin server (server/routes/prime.js). Workers lease segment blocks over HTTP GET/POST rather than WebSockets, enabling high-density task distribution and robust segment verification.

Section Order & Normal Appearance

1. Auth Bar: Shows session details and the logout-btn button.
2. Sitemap / Navigation: Direct links across director, monitor, and manual pages.
3. Worker Controls (Legacy): Contains collapsed legacy buttons (start-run-btn, stop-run-btn, pause-run-btn, resume-run-btn).
4. Server-Side Progress: Progress bar and metric cards polled from GET /prime/status every 2 seconds.
5. Worker Pool Snapshot: Summary count of live pool workers polled from GET /pool/summary.
6. Pool Workers Panel: Mounts shared pool_workers_panel.js filtered to prime workers.
7. SSPrime Task Log: Mounts worker_events_control.js providing logging switches and summary tables.
8. Client Log: Timestamped in-page diagnostic terminal logging operator actions.
9. SSPrime Operator Configuration & Controls (wo6-ssp-*): Single visible operational deck.
10. Cluster Dispatch Control: Mounted by control_renderer.js; provides clust-apply-ssprime.
11. Shared Persistence Panel: Mounts persistence_panel.js showing storage backend connectivity.

Configuration Inputs

• Upper Limit (N) (wo6-ssp-N): Search ceiling for prime sieve evaluation.
• Segment Size (wo6-ssp-seg): Number of values evaluated per segment pass (segmentK).
• Lease TTL (s) (wo6-ssp-ttl): Task deadline granted to each worker lease before lease expiry.
• Max Lease Want (wo6-ssp-want): Ceiling on number of segments a worker may lease in a single batch.

Controls Reference — SSPrime Director

5. Matrix Director (public/MatrixDirector.html)

The Matrix Director controls the distributed dense block-matrix multiplication pipeline (server/routes/matrix.js). It configures matrix dimensions, initializes task sets, leases matrix slices to dedicated Matrix worker tabs (WASM ABI V2), tracks the Hash-Chained Immutable Audit (HCIA) chain, and qualifies computation artifacts.

Section Order & Normal Appearance

1. Auth Bar: Displays session identity and logout-btn.
2. Matrix Admin Controls — Run Lifecycle: Houses btn-init, btn-run-pause, btn-run-resume, btn-run-stop, btn-run-restart inside a collapsed legacy container. phase-pill stays visible.
3. Matrix Admin Controls — Page & Evidence: Contains btn-refresh, btn-pause, btn-export, and anchor link to Matrix-Task-JSON-Logs.html.
4. Advanced Configuration (all fields): Collapsed container providing schema-driven inputs and buttons btn-config-stage, btn-config-reload, and btn-config-apply.
5. Feature Gates In Force: Read-only table of active feature flags fetched from GET /matrix/gates.
6. Audit Chain (HCIA) & Progress: Progress bars, task counters, and audit sequence tip verifying monotonic chain growth.
7. Shared Persistence Panel: Mounts persistence_panel.js showing active mode and journal metrics.
8. Archived Checkpoint Persistence (h5): Collapsed legacy persistence controls housing h5-apply.
9. Matrix Lane Workers: Direct table of Matrix worker tabs filtered from /pool/list by only-matrix checkbox.
10. Matrix Task Log: Mounts worker_events_control.js scoped to matrix lane.
11. Matrix Operator Configuration & Controls (wo6-mx-*): Primary visible operator control deck.
12. Cluster Dispatch Control: Mounted by control_renderer.js; provides clust-apply-matrix.

Configuration Inputs — Operator Deck

• Square Matrix Mode (wo6-mx-square): Checkbox locking dimensions M and K to N.
• M (rows), K (inner), N (cols) (wo6-mx-M, wo6-mx-K, wo6-mx-N): Matrix dimensions.
• Slices (wo6-mx-slices): Number of vertical/horizontal task slices to divide the matrix into.
• Tasks This Run (wo6-mx-tasks): Explicit total count of partition tasks generated for the run.
• Repetitions (wo6-mx-reps): Repetitions per slice for benchmarking stability.
• Lease Want (wo6-mx-want): Tasks requested per worker lease polling cycle.
• Max Concurrent Slots (wo6-mx-slots): Maximum concurrent computation slots per worker tab.
• Operation (wo6-mx-op): Matrix operation identifier (e.g. matmul).
• Preferred Backend (wo6-mx-backend): Preferred computation engine (wasm, cpu).
• Seed Base (wo6-mx-seed): Pseudo-random generator integer seed base for input matrices.

Controls Reference — Matrix Director

6. Worker Pool Administration (public/WorkerPool.html)

The Worker Pool dashboard lists every browser worker node registered in the Redis worker pool (/pool/list). It provides detailed telemetric visibility across worker identities, connection status, hardware capabilities, and cluster affinity, as well as operational controls for cluster tagging, bulk refresh broadcast, worker banning, and delayed eviction purging.

Column-by-Column Semantics

• Worker ID: Persistent client identifier derived from info.deviceId (held in browser localStorage under ccgsc_worker_id) with fallback to WorkerStats cache. Identifies physical browser profiles across multiple tabs on the same origin. Never displays ephemeral tab IDs. If metadata is missing, displays waiting deviceId.
• Tab ID: Ephemeral worker process identifier generated in browser sessionStorage and sent as Redis pool key. Uniquely distinguishes individual tabs.
• Status: Displays online badge if Redis lease TTL is active (ttl !== -2) or stale if expired, accompanied by operational mode text (e.g. Busy, Idle, Draining).
• TTL: Seconds remaining on worker connection lease key in Redis (workers:lease:<tabId>). Renewed continuously by worker heartbeats. Value of -2 indicates expired lease.
• Task: Currently assigned task ID. If a worker is executing an HTTP lease that does not publish an explicit ID (such as SSPrime), displays busy · id not published.
• CPU: Hardware concurrency reported by worker browser (navigator.hardwareConcurrency).
• Browser/OS: User agent string (first 60 characters), detected operating system, and device classification tag.
• Memory (heap): JS heap usage formatted as used/total MB. Displays n/a on Firefox, Safari, or non-Chromium browsers where the proprietary performance.memory API is unavailable.
• IP: Remote client IP address derived directly from the connection socket or reverse proxy headers (x-forwarded-for). Untrusted and XSS-escaped.
• Family: Worker family hint (e.g. matrix or generic).
• Lane: Resolved computation lane assignment. Appends (proof) when worker connects with proof telemetry enabled.
• Client: Client build and runtime ABI version reported by Matrix worker tabs (h6).
• Cluster: Resolved logical cluster ID with (tagged) badge if an administrative override exists. Operators with admin privileges can edit cluster tags inline. Submitting an empty tag clears the override.
• Last Seen: Timestamp recorded from the server gateway clock upon most recent heartbeat.
• Actions: Administrative action buttons (Ban, Unban, Purge, Cancel Purge) available when ADMIN_WRITE=1.

Controls Reference — Worker Pool

Row-Level Actions (Available when ADMIN_WRITE=1)

• Ban (POST /pool/ban/:id): Adds worker tab ID to Redis set workers:banlist. Checked upon worker registration (pool.register); banned connections are rejected with code 4001 (reason banned). Does not terminate active heartbeats immediately; takes effect on next reconnect.
• Unban (POST /pool/unban/:id): Removes tab ID from workers:banlist, allowing future registrations.
• Purge (POST /pool/purge/:id with { delaySec: 600 }): Schedules delayed purge in Redis ZSET workers:purge:pending. Row transitions to ticking button: Purging in m:ss · Cancel.
• Cancel Purge (POST /pool/purge-cancel/:id): Aborts scheduled purge prior to expiration of the 600-second countdown.
• Set Cluster (POST /pool/tag/:id with { clusterId }): Overrides worker cluster assignment in Redis. Submitting an empty string removes the override and restores worker-reported metadata.

7. Worker Pages & URL Flags

The public worker client (public/worker.html) attaches to the CCGSC cluster grid, registers hardware capabilities, and executes assigned tasks. URL query parameters control execution mode, lane filtering, and telemetric features:

8. Refusal Codes & Error Semantics

CCGSC servers reject invalid state mutations or unauthorized operations with specific semantic refusal codes:

9. Operational Recipes

Recipe 1: Start → Pause → Resume → Stop → Archive per Lane

1. IsPrime Lane:
   • Stage desired parameters using wo6-ip-stage.
   • Click wo6-ip-start (or composite wo6-ip-stagego) to begin computation.
   • To temporarily halt leasing, click wo6-ip-pause. In-flight tasks complete.
   • Click wo6-ip-resume to continue leasing.
   • To finish run, click wo6-ip-stop.
   • Click wo6-ip-clear to archive computation state and task logs to archive/isprime/<ts>/.
2. SSPrime Lane:
   • Stage search bounds with wo6-ssp-stage.
   • Click wo6-ssp-start to begin sieve leasing.
   • Pause with wo6-ssp-pause; resume with wo6-ssp-resume.
   • Stop with wo6-ssp-stop.
   • Archive evidence using wo6-ssp-clear (preserved in archive/ssprime/<ts>/).
3. Matrix Lane:
   • Stage dimensions and slice count with wo6-mx-stage.
   • Click wo6-mx-start to initialize the run.
   • Pause with wo6-mx-pause; resume with wo6-mx-resume.
   • Stop with wo6-mx-stop.
   • Archive run state using wo6-mx-clear (saved into archive/matrix/<ts>/).

Recipe 2: Switch Checkpoint Persistence Mode

1. Navigate to Matrix Director (/MatrixDirector.html).
2. Locate the Persistence panel (or expand the archived Checkpoint Persistence card).
3. Select the target mode from the dropdown:
   • compact-adaptive: Default; batches state saves dynamically between 0.5s and 10s.
   • compact-immediate: Saves state synchronously after every task report.
   • full-legacy: Preserves full pre-h5 legacy state serialization.
   • journal: Writes compact snapshots plus an append-only fsynced line journal (h8).
4. Click Switch mode (or h5-apply).
5. Confirm modal dialogue. The server writes an immediate full checkpoint, updates mode, and records an audit event.

Recipe 3: Rotate and Verify the Audit Chain

1. Navigate to IsPrime Director (/director.html).
2. Scroll down to the Audit Log & Rotation Card.
3. Click h7-audit-refresh to inspect current segment line count and error metrics.
4. Click h7-audit-rotate to manually trigger rotation.
5. The coordinator closes the active segment, starts background gzip compression, and opens a new segment.
6. Verify that Write Errors remains 0 and the chain sequence advances monotonically.

Recipe 4: Ban, Purge, and Cancel Purge for a Worker

1. Navigate to Worker Pool (/WorkerPool.html) with administrator privileges.
2. Locate the target worker tab row in the pool table.
3. To Ban: Click Ban. The server adds the tab ID to workers:banlist. The row updates to Banned. Future connection attempts will be rejected with code 4001.
4. To Purge: Click Purge. Confirm the confirmation prompt. The server schedules a 600-second eviction countdown in Redis. The button transforms into Purging in 10:00 · Cancel.
5. To Cancel Purge: Click the yellow Cancel button before the countdown reaches zero. The server issues /pool/purge-cancel/:id, removing the deadline.
6. If uncancelled, after 600 seconds the server sweep evicts the tab record and deletes its Redis keys.

10. Glossary

• Lane: An independent computational pipeline (IsPrime, SSPrime, or Matrix) operating over the shared worker grid.
• Tab ID: An ephemeral browser tab session key stored in sessionStorage. Identifies an individual tab connection in Redis.
• Device ID: A persistent browser profile identifier held in localStorage (ccgsc_worker_id). Identifies physical machines across multiple tabs on the same origin.
• Liveness TTL: The expiry lifetime of key workers:lease:<tabId> in Redis. Renewed continuously via worker heartbeat messages.
• Task Lease: A bounded assignment of a specific computation range or matrix slice granted to a worker tab with an execution deadline.
• Batch: A collection of candidate tasks or segments leased to a worker tab in a single HTTP request (batchK, maxWant).
• Cluster: A logical grouping of workers identified by a clusterId string used for selective task dispatching.
• Strict: A cluster affinity mode where workers outside the specified target cluster are refused all task leases.
• Affinity: A dispatch routing policy that prioritizes issuing task leases to workers matching the configured cluster ID while capping non-matching workers.
• Stage: Saving parameter modifications into in-memory staging storage without interrupting or modifying an actively executing run.
• Restore: The automated process of loading run checkpoints and reconciling task counters from persistent storage upon coordinator reboot.
• Purge (delayed): A scheduled eviction of an inactive or stale worker tab after a 600-second countdown, stored in Redis ZSET workers:purge:pending.
• Checkpoint Mode: The persistence strategy governing state flushes (compact-adaptive, compact-immediate, full-legacy, or journal).
• Slots / concurrentTasks: The worker page has NO slot setting. The single setting is the Director Delivery concurrentTasks, defining how many tasks one worker tab runs at the same time (IsPrime is locked to 1; Matrix 1–16, shipped at 10; SSPrime 1–4, shipped at 1). Older names for this same concept include Matrix "Max Concurrent Slots" (batchPolicy.maxConcurrentSlots) and WorkerPool "Compute Slots (1-3)" (gated off by CCGSC_LANE_POLICY). A Matrix tab still computes one task at a time today. Shipped warning: several tasks at once compete for the same CPU; only 1 has been measured. Safe use: leave 1.
• Max Concurrent Slots: See Slots / concurrentTasks.
• Compute Slots: See Slots / concurrentTasks.
• Run buttons: Start / Resume / Restart: In the IsPrime Director (WebSocket), Start New Run sends startComputation; Resume Run sends resumeComputation; Restart Run sends restartRun; and Stage & Start New Run stages candidate configuration and then starts computation. Resume Run only un-pauses the current run (retaining the same run ID, completed results, task queue, and log files; refused for a stopped run). Start New Run and Restart Run both archive the old run to archive/isprime/<timestamp>/, promote staged configuration, generate a new run ID, and rebuild the task queue. ONLY Restart Run also frees tasks that worker tabs are holding (and discards their late answers if N or the task count changed).