NODEDC_PLATFORM/device-plane/docs/IMPLEMENTATION_BASELINE.md

Device Plane Implementation Baseline

Status: PostgreSQL, Control Core and Gateway foundation are running healthy on Synology with public ingress, discovery ingest and commands disabled. The first application artifact is terminal-failed because its health gate timed out and its automatic rollback could not model the DB-bootstrap predecessor. Recovery is a separate source-only canonical transition; the failed artifact is never retried.

Product boundary

The Device Manager user interface is a canonical Foundry Page Library template. Foundry owns page instances, layout, presentation and an opaque device-plane-control binding. It does not own device records, credentials, raw protocol or command delivery.

The independent NDC Device Plane owns physical-device state and direct connections:

Foundry Device Manager Page
        |
        | device-plane-control (typed server boundary)
        v
Device Control Core <-> Device PostgreSQL
        |
        v
Device Gateway <-> physical devices

Engine L2 may consume safe decoded observations and build workflows/Data Products. It does not own TCP sessions, secrets or the command transport.

Preserved production path

The existing Gelios -> Engine L2 -> External Data Plane -> Foundry Map path is outside this implementation slice. Its credentials, workflows, Data Products, bindings and map presentation must not be changed or restarted by a Device Plane artifact.

The first B2 pilot adds an NDC server route in parallel and keeps the existing Gelios route unchanged.

Source and runtime placement

Source:

platform/device-plane/
  packages/device-protocol-contract/
  packages/arusnavi-b2-adapter/
  services/device-control-core/
  services/device-gateway/
  docker-compose.device-plane.yml

Planned Synology runtime:

/volume1/docker/nodedc-device-plane

Planned Compose project and services:

nodedc-device-plane
  device-control-core
  device-gateway
  device-postgres

device-postgres is a private persistent prerequisite. Application overlays must never force-recreate it or its volume.

The canonical runner selects only device-control-core and device-gateway with --no-deps. Its health acceptance is scoped to the selected services and requires the fail-closed fields to remain disabled. A failed first activation removes only candidate stateless services and never requests volume removal. Rollback now records an explicit pre-apply service inventory in the backup; the existence of the shared Compose file does not imply that Core or Gateway existed before apply.

The exact foundation recovery validates the failed archive, journal, backup, partial live source and observed healthy image/container generations. It then publishes the matching source and performs read-only runtime acceptance. It does not build, restart, recreate or remove any service.

Network boundary

The baseline publishes no device port. The planned pilot ingress is device.nodedc.ru:9921/TCP only after a port-collision check, quarantine/rate limits and a separate reviewed ingress transition.

DSM HTTP/HTTPS Reverse Proxy is not a raw TCP ingress and must not be configured as 443 -> 9921.

The artifact never changes DSM firewall, DSM Router Configuration, DNS or a physical router.

Identity and onboarding

An IMEI is a claimed protocol identifier, not proof of tenant ownership.

• An unknown connection produces a quarantine-only discovery.
• A discovery never receives commands.
• Pilot claim requires an explicit platform-admin action.
• Production assignment requires authoritative pre-enrollment or an audited inventory import.
• First-claim-wins by IMEI is forbidden.

The ARUSNAVI Web account login/password is used only by the human operator to configure the additional device route. It is not a Device Plane credential.

Protocol evidence

The official B2 material proves:

• four simultaneous monitoring server routes;
• INTERNAL, EXTERNAL, USER_AG and EGTS variants;
• INTERNAL server-side identification by modem IMEI;
• server route fields for DNS/IP, TCP port, protocol and optional ID;
• SMS/TCP command families and a six-digit device access password.

The public material inspected so far does not define enough exact INTERNAL packet framing and acknowledgement detail to implement a production decoder. The B2 adapter therefore hashes bounded evidence and fails closed. It does not search arbitrary bytes for a 15-digit sequence and call that an IMEI.

Command boundary

Outbound command transport is disabled in this baseline. No command builder is exported.

Later lifecycle:

draft -> planned -> awaiting_confirmation -> queued -> dispatched
      -> acknowledged | failed | expired | unknown

send is not success. An unknown result forbids automatic retry.

Erase, factory reset, firmware/custom firmware, physical outputs and arbitrary raw TCP remain forbidden until separate reviewed acceptance slices.

Implemented local foundation

• Provider-neutral discovery, contour and opaque Foundry-binding contracts.
• B2 model profile with four parallel routes and INTERNAL/IMEI evidence.
• PostgreSQL migration for model profiles, contours, quarantine discoveries, claimed devices, Foundry bindings and append-only audit events.
• Core health endpoint and an authenticated quarantine-ingest boundary that is disabled unless explicitly enabled with file-backed secrets.
• Gateway health endpoint and a loopback-only test listener that records only a bounded evidence hash, sends no acknowledgement and emits no identifier.
• Recursive rejection of secret-like fields, raw payloads and command-shaped input in presentation contracts.
• Automated contract, adapter, migration, Core and Gateway tests.
• Additive component=device-plane runner registry with exact roots, builds, services, allowlist/denylist, runner-owned secrets, health contracts and automatic source/runtime rollback.
• Deterministic data-only artifact builder and positive/negative regression tests.
• Compose foundation with a private internal network, preserved PostgreSQL volume, file-backed database password and loopback-only health publishing.
• Exact one-time PostgreSQL bootstrap descriptor, deterministic builder and absence preflight: an existing database container or volume fails closed, and rollback never removes the volume.

Next source slice

1. Promote the reviewed recovery-capable runner through the standalone root administrative gate and run a fresh verify-install.
2. Plan and apply the exact source-only foundation recovery artifact once, then reconcile its journal/backup and repeat runtime acceptance.
3. Obtain or capture the exact official B2 INTERNAL framing and acknowledgement contract; keep ingress disabled until its fixtures pass.
4. Add an authenticated internal Core/Gateway discovery boundary and explicit platform-admin claim operation.
5. Open raw TCP ingress only in a later reviewed slice after quarantine, framing, rate-limit and audit acceptance.