service-pointsav-link — planned PointSav fleet adapter

@@ -2,7 +2,7 @@
schema: foundry-doc-v1
title: "service-pointsav-link"
slug: service-pointsav-link
short_description: "service-pointsav-link is the hot-pluggable adapter that connects an os-* Subject node to a PointSav fleet, with a default state of not installed and a clean-severance failure mode."
short_description: "service-pointsav-link is a named but unbuilt adapter concept for connecting an os-* node to a PointSav fleet — no corresponding package exists in the monorepo today."
category: services
index_group: specialist-and-domain-services
type: topic
@@ -11,57 +11,43 @@ status: stable
bcsc_class: public-disclosure-safe
language: en
paired_with: service-pointsav-link.es.md
last_edited: 2026-06-23
last_edited: 2026-08-22
editor: pointsav-engineering
---

**Correction (2026-08-02, verified against canonical `origin/main`):** `service-pointsav-link` doesn't exist as a crate anywhere in the monorepo — confirmed on both branches, repeated finding from `security/diode-standard.md` (2026-07-30), `systems/totebox-archive.md`, and `infrastructure/sovereign-mesh.md` this session. No `pointsav-protocol` package exists either. This whole article describes an adapter with no corresponding code. **Flagged, not resolved.**
`service-pointsav-link` names a concept, not a shipped package: a hot-pluggable adapter that
would connect an `os-*` node to fleet management, translating authority commands into
subject-executable operations. No crate by this name, and no `pointsav-protocol` package,
exists anywhere in the platform's source. The concept appears in internal planning material
with a status of "conceptual" — scoped and named, not built.

`service-pointsav-link` is the hot-pluggable adapter that connects an `os-*` Subject node to a PointSav fleet. It is the sole code responsible for translating authority commands — issued by `os-network-admin` and delivered via the [[ppn-command-protocol|PPN Command Protocol]] — into Subject-executable operations. The adapter ships as the `pointsav-protocol` package. Its most important property is its default state: it is not installed. A Subject with no `service-pointsav-link` has no concept of phoning home, receiving commands, or participating in fleet management.
## What the design would do

## The four properties
The described shape, as recorded in planning material: a Subject node ships with the adapter
absent by default, so it carries no code capable of initiating contact with an authority. An
operator activates it with a single command, which installs the adapter and registers the
node with a fleet pairing registry. If the adapter crashes or is removed, the Subject keeps
running its own workloads — only the fleet's visibility into it goes dark. This shape, if
built, would be one concrete implementation of the [[diode-standard|Diode Standard]]: an
authority-to-subject channel with no reverse path for commands.

| Property | Behaviour |
|---|---|
| Default state | Not installed; the Subject has no concept of phoning home |
| Activated state | Hot-plugged by the operator with a single command; brings the Subject under fleet management |
| Failure mode | If the adapter crashes, the link severs cleanly; the Subject continues running standalone; the fleet management surface goes dark |
| Code path | Diode policy lives inside the adapter, not the OS kernel — the policy can be updated without touching the rest of the system |
## What exists instead

## Default state: no phone-home capability
The platform's real one-directional mechanisms are documented on [[diode-standard]], which
covers each in detail: a pull-and-wipe egress pair, a pull-based telemetry pipeline, an
ingestion component that names its own logic "the ingress diode," and a directional
code-promotion pipeline with hard reverse-flow guards. None of these is the adapter described
here, and none is a general-purpose fleet-command link — each satisfies the one-directional
rule for its own narrow purpose.

A freshly booted `os-infrastructure` node does not have `service-pointsav-link` installed. This is not a configuration choice — it is an architectural invariant. The Subject OS contains no code that would allow it to initiate contact with any authority. There is no `ssh` client, no peer-to-peer routing table, and no RPC initiator. The Subject is structurally incapable of phoning home.

This property holds across the entire `os-*` family. Every Subject — `os-totebox`, `os-mediakit`, `os-privategit`, `os-infrastructure`, and `os-network-admin` when acting as a Subject — begins in a state where fleet management is absent. Bringing a node under management is always an explicit operator action, never an automatic one.

## Activation: hot-plugging the adapter

An operator activates `service-pointsav-link` on a Subject with a single command issued from `os-network-admin`. The activation sequence installs the `pointsav-protocol` package, registers the node's fiduciary keypair with the fleet's pairing registry as a Subject entry, and opens the adapter's single inbound command channel.

After activation, the Subject becomes addressable by the fleet's command broadcast. The adapter's inbound channel listens on the PPN mesh and accepts only packets whose operation code is within the permitted set defined by the fleet's [[diode-standard|Diode Standard]] policy. All other traffic is discarded at the adapter boundary.

## Failure mode: clean severance

If `service-pointsav-link` crashes or is deliberately uninstalled, the Subject does not fail. It continues running its workloads — serving content, executing computations, maintaining its local state — as if fleet management had never been present. The fleet management surface goes dark: `os-network-admin` loses visibility of the Subject and cannot issue commands to it. But the Subject's own services are unaffected.

This failure mode is by design. A Subject that depends on the adapter for normal operation would be permanently coupled to the control plane — any control-plane outage would cascade to the Subject's workloads. By decoupling Subject operation from adapter presence, `service-pointsav-link` ensures that a control-plane failure is an observability loss, not a service outage.

## Policy in the adapter, not the kernel

The [[diode-standard|Diode Standard]] policy — which command flows are permitted, what operations are allowed from which authorities, what telemetry is emitted — lives inside `service-pointsav-link`, not in the Subject OS kernel. This separation has a practical consequence: updating fleet policy requires updating the adapter, not rebuilding or rebooting the operating system.

A Subject OS release and a Diode policy update are independent deployments. An operator can tighten or loosen fleet policy by pushing a new `pointsav-protocol` package version to active Subjects without touching any kernel code.

## The Universal Standard

`service-pointsav-link` is not a feature of a specific operating system. The same `pointsav-protocol` package, with different policy bindings, is the adapter between any pair of PointSav OS instances that need to communicate. An `os-totebox` Subject connected to an `os-console` Authority uses the same adapter code path as an `os-infrastructure` Subject connected to `os-network-admin`.

This uniform standard is what makes a complex fleet auditable. Every connection looks the same at the protocol layer. An auditor examining any pair of connected nodes sees the same adapter shape — the same default-off behaviour, the same activation sequence, the same clean-severance guarantee.
Whether this specific adapter is a planned component not yet built, or a design renamed or
superseded by one of those other mechanisms, is an open question flagged for the owning
engineering group. This article does not guess at an answer.

## See also

- [[diode-standard]] — the authority hierarchy and traffic rules the adapter enforces
- [[os-network-admin]] — the Authority that activates and commands Subjects via the adapter
- [[os-infrastructure-ppn-node]] — an os-infrastructure Subject that uses this adapter to join a fleet
- [[ppn-command-protocol]] — the 16-byte binary wire format the adapter receives
- [[machine-based-auth]] — the fiduciary keypairs that authenticate the adapter's command channel
- [[diode-standard]] — the design rule this adapter would implement, and the real mechanisms
  that follow it today
- [[machine-based-auth]] — how two machines authenticate before any connection, real or
  conceptual, is permitted
- [[os-network-admin]] — the authority side this adapter's design would connect to