Skip to content

PointSav Documentation

The engineering library for the PointSav platform — operating systems and services for regulated businesses that own their data, their AI, and their record-keeping outright. Where the monorepo holds the code, this wiki holds the reasoning: architecture, services, security, and the governance commitments that bind future development.

PointSav Digital Systems

Last updated · f754176e · Español

PPN VM resource pool architecture

The PointSav Private Network (PPN) VM resource pool is a three-service stack that provisions, places, and accounts for virtual machines across a heterogeneous WireGuard mesh. The pool combines cloud nodes with physical hardware, forming a distributed compute substrate that spans different capability profiles.

Three services partition the responsibility surface. The fleet controller maintains a global view of node capacity and handles placement decisions. The host agent runs per-node as the spawn authority, communicating with the hypervisor and holding the local state for each VM. The tenant proxy sits at the customer boundary, enforcing authentication, tenant namespace isolation, quota limits, and an immutable audit trail.

All service processes communicate across the PPN WireGuard underlay. No service exposes a public interface; all customer-facing traffic enters through the tenant proxy.

Fleet controller

The fleet controller maintains an in-memory registry of node state: available capacity, hardware virtualisation availability, current VM count, and reservation status.

Placement uses a two-pass selection algorithm. The first pass considers only non-reserved nodes, satisfying the requested capacity ceiling. If the first pass yields no candidate, the second pass widens the search to include reserved nodes. This separation allows operators to designate nodes for latency-sensitive workloads while still permitting overflow placement under load.

Fleet status endpoints provide a global view of node state and per-tenant VM listings. Heartbeat ingestion from host agents is trust-bounded by the WireGuard underlay and node identity, not by separate credentials.

Host agent

The host agent is the per-node spawn authority. Each node in the pool runs one instance, which accepts spawn and destroy requests forwarded by the fleet controller after placement.

On receiving a spawn request, the agent assembles the required initialisation configuration, invokes the hypervisor with the appropriate parameters, and writes state metadata alongside the disk image. This sidecar stores the VM identifier and enables heartbeat recovery after a process restart or node reboot without querying the fleet controller.

Nodes signal their reservation status and stable identity to the fleet controller at startup. Nodes where hardware virtualisation (KVM) is unavailable — such as cloud instances without nested virtualisation — report this capability flag in their heartbeat; the hypervisor falls back to software emulation on those nodes.

Tenant proxy

The tenant proxy is the customer-facing layer. It accepts spawn, destroy, and status requests from authenticated callers and enforces the tenant contract before forwarding to the fleet controller.

Authentication is bearer-token based, with each tenant assigned a max_vms/max_ram_mb quota at provisioning time. A tenant may not query, modify, or destroy VMs belonging to another tenant; the proxy enforces this at every endpoint before any fleet interaction. With an explicit token-to-tenant map configured, a bearer token is opaque and resolves to a tenant identifier server-side. Without one, the bearer token doubles as the tenant identifier directly — a documented, less-hardened fallback mode, not the sole authentication path.

Quota enforcement checks current allocated capacity against the ceiling before forwarding a spawn request; requests that would exceed the quota are rejected. Concurrent create requests are serialised through a single lock shared across all tenants, not a separate gate per tenant, closing the same TOCTOU window a per-tenant gate would but without per-tenant concurrency.

Every write operation is appended to a local, append-only audit file (timestamp, tenant identifier, operation, VM identifier) and forwarded, best-effort, to service-fs's WORM ledger as a durable secondary record; the local file remains authoritative if that forward fails.

WireGuard mesh

The PPN underlay uses a WireGuard mesh. All service processes bind to their WireGuard interface addresses, not to public interfaces. Peer configuration is static; each node holds the public keys of its peers and the routing ranges for each tunnel.

A cloud relay node forwards traffic between physical nodes that are on separate networks without a direct route, though WireGuard uses direct peer paths when available. The relay role does not require the cloud node to participate in VM placement — it operates at the network layer only.

Node heterogeneity is a deliberate property of the pool. Each node type contributes a different capability profile: cloud nodes provide reliable uptime and elastic storage; physical nodes provide hardware-accelerated virtualisation. Placement decisions reflect these differences through the capability flag and the two-pass reserved/non-reserved selection algorithm.

Planned extensions

Three extensions to the compute substrate are intended for future deployment; none is operational today.

Microkernel isolation (planned/intended): The VM spawn path on AArch64 hardware is intended to use a formally-verified microkernel component model. The intended design would replace the host kernel as the trust boundary for VM isolation, providing formal verification of the scheduler and inter-process communication paths between VMs.

Lightweight microVM (planned/intended): An alternative hypervisor backend is under evaluation for workloads where sub-second boot time and reduced memory overhead are priorities. The intended integration point is the host agent, which would select the hypervisor backend based on the workload type specified in the spawn request.

Bare-metal provisioning ISO (planned/intended): A signed, reproducible boot image is intended as the provisioning substrate for new PPN nodes. The planned design is intended to install the full node stack from a single boot, without requiring an existing operating system install or manual configuration.

See also

Cite this record: /wiki/ppn-vm-resource-pool — revision f754176e, last updated 24 August 2026.

Important Information

Corporate structure. PointSav Digital Systems ("PointSav") is currently a trade name of Woodfine Capital Projects Inc. ("Woodfine"), planned to become a wholly-owned Woodfine subsidiary upon incorporation. PointSav does not itself offer, sell, or solicit any security. Any securities offering associated with Woodfine's real-property direct-hold solutions is made exclusively by Woodfine, and only by means of the applicable Private Placement Memorandum.

No investment advice. This wiki's content is provided for engineering, operational, research, and development purposes. Nothing on this wiki constitutes investment advice or a solicitation to invest in any Woodfine partnership or direct-hold solution.

Intellectual property. The PointSav name, trade name, wordmark, and marks, together with all current and future PointSav- and Totebox-branded products, services, and offerings — and the software, source code, documentation, design system, and all related materials — are proprietary to Woodfine and its affiliates, except for components identified as open source. No rights are granted except as expressly set out in a written license or agreement. The full trademark notice appears in the footer of every page on this site.

Open source components. Portions of the platform are made available under permissive open-source licenses identified in the accompanying repository. Use of those components is governed by their respective license terms.

No warranty; informational use. Content on this wiki is provided for general informational purposes only and does not constitute a representation, warranty, or commitment with respect to product functionality, availability, pricing, or roadmap. Some articles describe planned or intended features, capabilities, and milestones — language such as "planned," "intended," "targeted," "may," and "expected" marks this forward-looking content, which is subject to change and does not constitute a commitment regarding future performance.

Confidentiality. Where an article describes an operational or deployment detail that is not intended for public disclosure, that article is not published on this wiki. Content here is general-purpose engineering documentation, not customer-specific configuration.

Jurisdiction. Woodfine Capital Projects Inc. is organized in British Columbia, Canada. References to the Sovereign Data Foundation on this wiki describe a planned or intended initiative only, not a current equity holder or active governance body.

Changes to this notice. PointSav may update this notice from time to time; the version posted on this page governs.

Not a filing system. This wiki is not a securities filing system, an electronic disclosure repository, or a substitute for SEDAR+ or any other regulatory filing system. Formal securities filings are made through the applicable regulatory filing system, not through this wiki.

Full disclaimer. This notice supplements, and does not replace, the full Disclaimers article. In the event of any conflict, the full Disclaimers article governs.

Read the full disclaimer →