NetworkAccess Pilot Program
NetworkAccess Pilot Program — Design
Status: approved direction, 2026-07-02. The 6-month program that takes Vinxi Kernel from zero code to a Jio-facing NetworkAccess pilot. Companion to the-seam.md (physics), ports-and-adapters.md (architecture contract), lld.md (port depth). Product requirements corpus: the SmartInventory/SmartOps/SmartProject detailed user stories v3.1.
1. Mission & posture
Build the Vinxi Kernel spine and NetworkAccess as its first Reality Package, co-developed as one vertical slice, greenfield. The existing SmartInventory suite is the executable spec and the migration payload; zero legacy code is carried forward.
Scale-readiness from day 1 is achieved by contract discipline, not big infrastructure: Lean-profile adapters behind the permanent ports, cell-safe Tier-1 contracts, and evidence-gated graduation (FDB / Flink / Redpanda / Trino stay out until observed thresholds demand them — LLD §8). “Scale down to scale up” means: everything runs small on day 1, and nothing in a contract prevents it from running at Jio scale by adapter swap and cell fan-out.
The 6-month milestone (≈ Jan 2027): a Jio-facing pilot on Lepton’s own amplified demo data, installed from signed bundles on on-prem infrastructure. No external data dependency sits on the critical path.
2. Decisions locked
| # | Decision | Consequence |
|---|---|---|
| 1 | Co-developed vertical slice; NetworkAccess authored as a Reality Package from commit 1 | ”Shape, not meaning” enforced structurally; telecom semantics never enter the kernel |
| 2 | Greenfield; legacy = spec + data | Stories doc = requirements corpus; smartinventory_qa DB = migration payload; no compatibility API |
| 3 | Pilot slice: inventory spine + one governed write loop (inbound feed = stretch) | Field capture → validation queue → approve/commit → audit, on a migrated, map-served, traceable inventory |
| 4 | Rust-first core and systems; TS userland | Geo/batch included (GeoRust, gdal-rs, GeoArrow, SedonaDB/DataFusion). Java held as an option (Flink graduation, JVM-only tooling), not a committed lane |
| 5 | Per-port language & adapter choices decided at build time, on evidence | Each choice recorded as a one-line ADR; the ports are the commitment, the implementations are not |
| 6 | Single cell for the pilot; cell-safe contracts from day 1 | No global-order or single-cell assumption in any Tier-1 contract; multi-cell later is deployment, not redesign |
| 7 | Realm = domain namespacing; Cell = shard (scale/placement unit) | Circles are not realms; circle→cell mapping is a later capacity decision |
| 8 | Pilot data = demo dataset (~1M entities), amplified ~5–10× to circle envelope | The “circle synthesizer” is a deliverable; a real operator extract can swap in post-pilot |
| 9 | Pod exists with skill gaps | Month 1 includes deliberate AI-assisted Rust ramp on the smallest viable Rust surface |
3. Decisions open by design (decide on the go)
- Cell addressing — is realm part of the cell address, or are cells purely physical placement resolved by routing (logical refs carry realm only; ordering tokens carry cell provenance)? First question the M1 “Cells & placement” doc answers. Ordering-scope of
OrderTokenfollows from it. - Query router shape (P11/read routing), P8 materializer topology, tile-serving split (dynamic vs baked per layer), Assert-store engine (Timescale vs ClickHouse — decided by feed volume if the stretch lands). Defaults exist in the LLD; each is chosen when its port is built, with an ADR.
4. Demo-data census (measured 2026-07-02)
smartinventory_qa @ 192.168.1.40:5014 — Postgres 14.8 (Windows), PostGIS 3.2.2, pgrouting, 8.4 GB:
- ~1.0M entities: 425k points / 265k lines / 143k polygons — poles 183k, buildings 143k, cables 95k, ducts 94k, manholes 85k, trenches 76k, splice closures 2.9k
att_details_cable: 329 columns → ontology mapping is the dominant migration cost, not row volume- Connectivity:
connection_info26.5k,isp_port_info301k, splice trays / patchcords / fiber links present entity_status_history: 1.35M rows (legacy proto-decision-log) + per-entityaudit_*tables- SRID 4326 uniform; ~70
vw_att_details_*_reportviews enumerate the entity-type catalog
Migration posture: current state enters as Asserts under an EXTERNAL_SOR manifest; legacy audit history stays archived/queryable — we never reconstruct a DecisionLog from history that didn’t pass a seam.
5. Scale envelope (per-cell benchmark targets, derived; validate against operator figures when available)
| Dimension | Circle envelope (pilot cell) | National ceiling (design headroom) |
|---|---|---|
| Entities | 2–10M | 50–300M across cells (cores/ports as traits, not entities) |
| Links | 10–50M | ~1B across cells |
| Acts | 25/s peak; gate at 500/s sustained | ~500/s national peak |
| Asserts | 0.5–2k/s sustained | 5–20k/s sustained; 50–100k/s storm |
| Concurrent users | 2–5k | 50–100k |
| Read p99 | point <50ms · queue <200ms · trace <500ms · tile <150ms | same, per cell |
| Bulk migration | 1M rows <4h; amplified 10M <24h | per-cell, parallelizable |
6. Workstreams
- W1 · Kernel spine (Rust — the ramp target): P0 registry → P1 Postgres+PostGIS, txn-outbox + cell-safe OrderToken → P2 NATS JetStream (DecisionLog + SchemaLog first) → seam v0 (Keycloak P15, OpenFGA P12, Cedar P13, signed-JWT→Biscuit-target P14) → custom P8 materializer → P23 with
ResolvedValuefrom day 1 → P9 trusted-worker interim with dated WASM retirement plan. - W2 · Data & geo (Rust-first, productive week 1): P0
MappingRefauthoring (329-col cable → traits), P17bulkLoad+ medallion staging against the QA instance, the circle synthesizer (pattern-preserving amplifier), P24 tiles (Martin dynamic + tippecanoe/Planetiler→PMTiles baked), the benchmark harness that owns every gate. - W3 · Userland (TS): IR→TS SDK codegen loop early (it gates everything downstream), web shell + Surface v0 (zone map, validation queue), field-capture PWA (
mediakind, GPS-stamped photos), offline v0 = device micro-branch (LLD §22). - W4 · Platform (shared, part-time): on-prem K8s, CI with the SDK round-trip as a gate, SigNoz, signed install bundles, security baseline.
7. Phase ladder (Jul → Dec 2026; pilot Jan 2027)
| Phase | Builds | Gate (hard, measured) |
|---|---|---|
| M1 Jul — spikes + skeleton | Spikes S1–S8 · walking-skeleton thread · Cells & placement doc · ontology draft v0 from the ~70 entity views | Skeleton round-trip: schema Act → entity Act → outbox → log → materialize → P23 → Query → generated TS SDK compiles; every spike meets kill-criteria or fallback chosen |
| M2 Aug — spine + data in | bulkLoad v0 · full demo DB migrated · map v0 | 1M-entity migration <4h · tiles p99 <150ms @100k viewport · 500 Acts/s sustained |
| M3 Sep — circle scale | Amplifier → 5–10M entities · Query IR v0 (Select/Spatial/Traverse/Trace) · two-tier authz (depth-aware scopes) | Circle-envelope green (point <50ms, trace <500ms p99) · authorized list-queries with zero per-row checks |
| M4 Oct — the write loop | Field-capture PWA · offline device-branch · validation-queue Surface · Pending(approval) + structured rejections | Internal field dry-run passes · offline merge fixtures (overlap/precondition/policy-drift) pass · audit end-to-end |
| M5 Nov — hardening | Rebuild-from-truth drill (wipe P1/P23/P5, rebuild) · 72h soak · erasure envelope check · stretch: one EXTERNAL_SOR CDC driver | Rebuild drill passes · soak clean, p99s hold |
| M6 Dec — pilot assembly | Scripted demo journeys (migrate→view→trace→capture→approve→audit) · install bundles · Jio narrative (picture / gate / story / rehearsal) | Full pilot runs from clean signed-bundle install on fresh infra |
8. Spike register (M1, parallel)
| # | Risk | Spike | Kill criterion |
|---|---|---|---|
| S1 | Outbox+OrderToken ceiling | Synthetic Act storm on skeleton | 500 Acts/s/cell sustained; read-your-write <50ms |
| S2 | Trace() at depth | Recursive CTE vs closure table vs pgrouting on real connectivity data | ring/path trace <500ms p99 |
| S3 | Tiles at 100k viewport with policy filtering | Martin dynamic vs baked PMTiles | tile <150ms; scope filtering correct |
| S4 | bulkLoad throughput | QA-instance extract → staged → typed Asserts via batch P8 | 1M rows <4h with validation report |
| S5 | ReBAC list-filtering | OpenFGA + marking predicates, two-tier | authorized lists, no per-row checks; point check <5ms |
| S6 | IR→SDK loop | P0 v0 → Reality IR → branded TS package in CI | schema Act regenerates compiling SDK; hallucinated action fails typecheck |
| S7 | Offline merge correctness | Device-branch replay harness + conflict fixtures | correct adjudication items; no silent loss |
| S8 | WASM sandbox viability | Wasmtime + verb-table host functions, one TS→WASM action | if painful → trusted-worker interim with retirement date |
9. Risks & pre-chosen fallbacks
| Risk | Fallback (chosen now, not in crisis) |
|---|---|
| Rust ramp too slow | Shrink Rust to seam + outbox + materializer; adjacent services in whatever the pod ships fastest, behind the same ports |
| 329-column mapping explodes | Map ~30 load-bearing traits per type; tail → document kind with its declared graduation story (LLD §19-F3) |
| WASM not ready | Trusted-worker interim (documented, dated) until customer/agent code exists |
| Tile policy-partitioning complexity | Hybrid strategy (c): coarse-safe baked pyramid + sensitive-dynamic layer |
| Cell assumptions leaking into contracts | Cell-safety checklist reviewed per port at every M-gate |
10. Out of scope for the 6 months
SmartProject, WFM/rostering, BOQ/rate-cards, DTP planning engine, AI-RCA/forecasting, OGC/TMF surfaces, schematic view, multi-cell runtime, Scale-tier adapter graduations, full Biscuit attenuation (signed JWTs first).
11. Next step
Implementation plan for M1 (spikes + walking skeleton + Cells doc + ontology draft), produced via the writing-plans process; repo scaffolding (Rust workspace, TS workspace, benchmark harness, CI) is part of that plan.