From b963ff87c6ce20c61655d5142b089de394a24691 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:03 +0200 Subject: [PATCH 01/20] docs(product): add README --- docs/product/README.md | 119 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/product/README.md diff --git a/docs/product/README.md b/docs/product/README.md new file mode 100644 index 0000000..9e453b1 --- /dev/null +++ b/docs/product/README.md @@ -0,0 +1,119 @@ +# spod Product Wiki + +This wiki defines what `spod` is as a product, who it is for, which workflows it should provide, and how those capabilities relate to Siderust. + +> **spod is operational Precise Orbit Determination infrastructure built on Siderust.** + +Siderust owns reusable scientific and numerical primitives. `spod` turns those primitives, external datasets, mission configuration, and operational policy into reproducible POD jobs, products, quality reports, and service interfaces. + +## North Star + +```text +onboard GNSS observations + + +precise supporting products + + +mission configuration + | + v + spod + | + +-- resolve and validate inputs + +-- construct the POD problem + +-- orchestrate Siderust science + +-- estimate and assess convergence + +-- apply operational QC policy + +-- write standard products + +-- record full provenance + | + v +precise orbit + QC + artifacts + manifest +``` + +The North Star milestone is tracked in [#20](https://github.com/VPRamon/spod/issues/20). + +## Product boundary + +### Siderust owns + +- physical and astrodynamics models; +- propagation and numerical algorithms; +- estimators; +- observation models; +- coordinate/time/unit primitives; +- standard file-format parsers and writers; +- reusable scientific QC primitives; +- reusable product serialization. + +### spod owns + +- job and workflow definitions; +- mission configuration; +- input resolution and acquisition policy; +- orchestration of Siderust components; +- artifact layout and publication; +- operational QC policy; +- provenance and reproducibility; +- CLI and REST interfaces; +- fleet/reprocessing orchestration; +- observability; +- deployment and operational behavior. + +The rule is not `if Siderust implements it, spod stops supporting it`. + +> **If Siderust implements the science, spod should consume it instead of duplicating it while preserving the product capability.** + +See [Feature parity policy](feature-parity-policy.md). + +## Wiki map + +- [Product vision and positioning](product-vision.md) +- [Personas and buyers](personas-and-buyers.md) +- [Capability map](capability-map.md) +- [Feature parity policy](feature-parity-policy.md) +- [Commercial model and packaging](commercial-model.md) +- [Commercial/product roadmap](commercial-roadmap.md) +- [Use cases](use-cases/README.md) + +## Primary use cases + +| Use case | Primary customer | Product value | Tracking | +|---|---|---|---| +| Operational onboard-GNSS POD | LEO/EO operator | Precise orbit products without building a POD stack | [#20](https://github.com/VPRamon/spod/issues/20) | +| Fleet / constellation POD | Constellation operator | Repeatable processing across many spacecraft | [#31](https://github.com/VPRamon/spod/issues/31) | +| Independent orbit validation | Operator / integrator | Independent confidence and quality gate | [#24](https://github.com/VPRamon/spod/issues/24) | +| Mission commissioning | Mission operations | Validate GNSS tracking and POD readiness | [#30](https://github.com/VPRamon/spod/issues/30) | +| Historical reprocessing | Science / operations | Reproduce historical products under new baselines | [#25](https://github.com/VPRamon/spod/issues/25) | +| Multi-latency operations | Operational ground segment | Rapid vs final processing policy | [#26](https://github.com/VPRamon/spod/issues/26) | + +## Product enablers + +- product capability parity and migration discipline - [#19](https://github.com/VPRamon/spod/issues/19) +- dataset resolution and acquisition - [#21](https://github.com/VPRamon/spod/issues/21) +- mission profiles - [#22](https://github.com/VPRamon/spod/issues/22) +- operational QC / run health - [#23](https://github.com/VPRamon/spod/issues/23) +- observability - [#27](https://github.com/VPRamon/spod/issues/27) +- stable product/artifact API - [#28](https://github.com/VPRamon/spod/issues/28) +- SGP4/SDP4 parity preservation - [#29](https://github.com/VPRamon/spod/issues/29) + +## Product principles + +1. **Capabilities are more important than module paths.** +2. **No silent scientific downgrade.** +3. **Every run is auditable.** +4. **CLI and REST are interfaces to the same product.** +5. **Operational policy belongs in spod; reusable science belongs in Siderust.** +6. **Automation is a feature, not an external shell script.** +7. **Quality is an output.** A generated orbit is not enough; the service must explain whether it is fit for its configured operational purpose. + +## Current status + +`spod` is an engineering preview. The deterministic synthetic workflow proves the service boundary and artifact/provenance model, but the product is not commercially complete until a real-data workflow is operational. + +The key transition is: + +```text +synthetic reference workflow + -> +real onboard GNSS data -> operational precise orbit product +``` \ No newline at end of file From 4aa5455f9f85e7ac91410a416dd439c77ae8f816 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:05 +0200 Subject: [PATCH 02/20] docs(product): add product-vision --- docs/product/product-vision.md | 99 ++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/product/product-vision.md diff --git a/docs/product/product-vision.md b/docs/product/product-vision.md new file mode 100644 index 0000000..5c3c6e8 --- /dev/null +++ b/docs/product/product-vision.md @@ -0,0 +1,99 @@ +# Product vision and positioning + +## Vision + +`spod` should make operational Precise Orbit Determination consumable as infrastructure. + +A user should describe the mission, input datasets, processing policy, requested products, and quality requirements, and receive a reproducible POD job result without assembling scientific primitives manually. + +## Product promise + +> Given tracking data, supporting products, and a mission configuration, `spod` produces a controlled, auditable POD run with standard orbit products, diagnostics, quality status, and provenance. + +## Why this is different from Siderust + +Siderust is a scientific software platform. It provides reusable parsers, propagators, observation models, estimators, QC primitives, and product writers. + +`spod` answers a higher-level operational question: + +> Run the supported POD workflow for this spacecraft and tell me what happened. + +Its product value is composition and operationalization. + +## Target architecture + +```text +operator / system + | + CLI / REST + | + spod + +---+---------------------------+ + | configuration / jobs / QC | + | inputs / artifacts / policy | + +---+---------------------------+ + | + Siderust + +---+---------------------------+ + | formats / POD / astrodynamics| + +-------------------------------+ +``` + +## What spod should become excellent at + +### Reproducible operations + +Every run should preserve effective configuration, mission-profile version, exact datasets and hashes, software versions, processing baseline, outputs, and quality decisions. + +### Productized workflows + +Scientific APIs are flexible; a commercial product needs supported paths such as: + +```text +leo-gnss-final +leo-gnss-rapid +orbit-validation +mission-commissioning +historical-reprocessing +``` + +### Quality gates + +The service should distinguish execution success, scientific convergence, and operational quality. + +### Automation + +Dataset resolution, mission profiles, campaigns, fleet orchestration, retries, and product publication should be product features rather than ad-hoc scripts. + +### Deployment + +`spod` should support local CLI, container deployment, internal REST service, and eventually managed execution without forking the scientific behavior. + +## Primary market wedge + +The initial target customer is a LEO operator or ground-segment integrator with onboard GNSS measurements who needs precise orbit products without maintaining a bespoke POD software stack. + +The first commercial-grade workflow should therefore be: + +> **Onboard GNSS -> precise LEO orbit + QC + provenance.** + +## Product extensions + +- constellation/fleet processing; +- independent orbit validation; +- commissioning; +- historical reprocessing; +- rapid/final processing classes; +- SLR validation; +- DORIS workflows; +- mission-specific workflows supported by the underlying scientific engine. + +## Non-goals + +`spod` should not become a general astrodynamics library, a duplicate of Siderust, a desktop mission-analysis suite, or a repository for algorithms with no operational POD use case. + +## Differentiation target + +> **headless, API-first, reproducible, container-native, operational POD.** + +Differentiation should come from workflow reliability, integration, provenance, quality reporting, and deployability, not from owning more implementations of standard scientific algorithms. \ No newline at end of file From f8b8e6c23eb619fa2097a9b67fa3fc3b07412ce1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:08 +0200 Subject: [PATCH 03/20] docs(product): add personas-and-buyers --- docs/product/personas-and-buyers.md | 63 +++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/product/personas-and-buyers.md diff --git a/docs/product/personas-and-buyers.md b/docs/product/personas-and-buyers.md new file mode 100644 index 0000000..42a34a4 --- /dev/null +++ b/docs/product/personas-and-buyers.md @@ -0,0 +1,63 @@ +# Personas and buyers + +## LEO / Earth-observation operator + +**Needs:** routine precise orbit products, predictable latency, reproducibility, low operator intervention, and explicit QC. + +**Pain:** maintaining a full POD stack is specialized; input versions and ad-hoc scripts make reproducibility and support difficult. + +**Buying trigger:** first operational mission, scaling beyond one spacecraft, or replacing fragile internal processing. + +## Ground-segment integrator + +**Needs:** a deployable POD component with stable APIs, versioned configuration, deterministic artifacts, and clear errors. + +**Pain:** every mission otherwise becomes a custom integration around scientific libraries. + +**Buying trigger:** standardizing multiple ground segments or needing an on-prem/containerized supported product. + +## Flight-dynamics / POD engineer + +**Needs:** diagnostics, mission profiles, baseline comparisons, residual inspection, and controlled overrides. + +**Pain:** too much glue code and poor traceability between data, configuration, and outputs. + +**Role:** technical champion and primary scientific user. + +## Mission commissioning team + +**Needs:** early assessment of GNSS availability, time tags, clock behavior, residuals, convergence, and comparison against external/onboard solutions. + +**Pain:** commissioning evidence is often assembled manually and problems are hard to localize. + +## Constellation operations team + +**Needs:** controlled processing across dozens/hundreds of spacecraft, independent retries, fleet QC, and safe baseline rollouts. + +**Pain:** per-spacecraft scripts and configuration drift do not scale. + +## Science / reprocessing team + +**Needs:** reproducible long-period reprocessing, processing baselines, restartable campaigns, and old/new baseline comparison. + +**Pain:** algorithms and reference products evolve, but historical processing is difficult to reproduce. + +## Platform / SRE team + +**Needs:** containers, structured logs, metrics, health endpoints, failure categories, and predictable resource behavior. + +**Pain:** scientific applications often expose only process exit codes and unstructured logs. + +## Buying-center summary + +| Persona | Primary concern | Likely role | +|---|---|---| +| Mission/operator lead | reliable orbit products | economic buyer | +| Ground-segment integrator | integration/deployment | buyer / partner | +| Flight-dynamics engineer | scientific quality | technical champion | +| Commissioning engineer | early mission validation | user/champion | +| Constellation ops | scaling/reliability | buyer/user | +| Science processing | reproducibility | user/buyer | +| SRE/platform | operability | approver/user | + +A commercially credible `spod` must satisfy both the scientific champion and the operational/platform buyer. \ No newline at end of file From 1bc942f83d566ca89c50da41443a4b285f1e071d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:52 +0200 Subject: [PATCH 04/20] docs(product): add capability-map --- docs/product/capability-map.md | 80 ++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/product/capability-map.md diff --git a/docs/product/capability-map.md b/docs/product/capability-map.md new file mode 100644 index 0000000..7194088 --- /dev/null +++ b/docs/product/capability-map.md @@ -0,0 +1,80 @@ +# Capability map + +This document maps product capabilities to their intended long-term owner. The detailed parity inventory is tracked by [#19](https://github.com/VPRamon/spod/issues/19). + +## Disposition vocabulary + +- **KEEP IN SPOD** - service/application capability. +- **MIGRATE TO SIDERUST** - product capability remains, implementation becomes canonical upstream. +- **UPSTREAM GAP FIRST** - capability must not be deleted until upstream has required semantics. +- **DECISION REQUIRED** - explicit product decision needed. +- **ADD TO SPOD** - missing product/application capability. + +## Existing capabilities + +| Capability | Product relevance | Intended owner | Disposition | +|---|---|---|---| +| Run configuration | core | spod | KEEP IN SPOD | +| Job execution | core | spod | KEEP IN SPOD | +| Artifact layout | core | spod | KEEP IN SPOD | +| Run provenance/manifests | operational policy around reusable primitives | spod + Siderust | KEEP IN SPOD | +| CLI | core interface | spod | KEEP IN SPOD | +| REST API | core interface | spod | KEEP IN SPOD | +| Docker/deployment | operations | spod | KEEP IN SPOD | +| Synthetic reference workflow | integration/reference | spod + Siderust | KEEP IN SPOD | +| Force models | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| Propagation / STM | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| WLS / nonlinear estimation | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| Observation models | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| Generic QC statistics | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| SP3/OEM serialization | standard product primitive | Siderust | MIGRATE TO SIDERUST | +| TLE / 3LE / OMM | standard formats | Siderust | MIGRATE TO SIDERUST | +| SP3 / RINEX / ANTEX / SINEX / ORBEX | standard formats | Siderust | MIGRATE TO SIDERUST | +| EOP / CRD / CPF / OEM / OPM / TDM | standard formats | Siderust | MIGRATE TO SIDERUST | +| SPICE / SPK | scientific/format primitive | Siderust | MIGRATE TO SIDERUST | +| Full Vallado SGP4/SDP4 | useful operational capability | canonical Siderust ecosystem backend | UPSTREAM GAP FIRST - [#29](https://github.com/VPRamon/spod/issues/29) | +| Lambert solver | generic mission-design function | ecosystem | DECISION REQUIRED | +| LISA-specific functionality | mission-specific | TBD | DECISION REQUIRED | +| DORIS workflow | potential POD workflow | spod + Siderust | DECISION REQUIRED / likely future | +| Parquet export | product/export capability | Siderust serializer + spod policy | KEEP if used by supported workflows | + +## Missing product capabilities + +| Capability | Why it belongs in spod | Tracking | +|---|---|---| +| Real onboard-GNSS POD | core commercial workflow | [#20](https://github.com/VPRamon/spod/issues/20) | +| Dataset resolution/acquisition | operational orchestration | [#21](https://github.com/VPRamon/spod/issues/21) | +| Versioned mission profiles | application configuration | [#22](https://github.com/VPRamon/spod/issues/22) | +| Operational QC / run health | service policy | [#23](https://github.com/VPRamon/spod/issues/23) | +| Independent orbit validation | product workflow | [#24](https://github.com/VPRamon/spod/issues/24) | +| Reprocessing campaigns | orchestration | [#25](https://github.com/VPRamon/spod/issues/25) | +| Latency/processing classes | operational policy | [#26](https://github.com/VPRamon/spod/issues/26) | +| Metrics / observability | operations | [#27](https://github.com/VPRamon/spod/issues/27) | +| Stable product/artifact API | service interface | [#28](https://github.com/VPRamon/spod/issues/28) | +| Mission commissioning | product workflow | [#30](https://github.com/VPRamon/spod/issues/30) | +| Fleet/constellation orchestration | scale/operations | [#31](https://github.com/VPRamon/spod/issues/31) | + +## Target public concept model + +Long-term `spod` concepts should look more like: + +```text +MissionProfile +RunConfig +Job +JobStatus +Workflow +ResolvedInputs +RunResult +Artifact +QcReport +RunManifest +Campaign +Fleet +``` + +and less like a second scientific namespace such as `spod::forces`, `spod::estimation`, `spod::tle`, `spod::spice`, or `spod::lambert`. + +## Important distinction + +Removing an old Rust API such as `spod::tle::parse_tle` does not imply removing the ability for a supported `spod` workflow to accept TLE data. The workflow should call `siderust::formats::tle` directly while preserving the product capability. \ No newline at end of file From d00274e91460ac4855769b5714f1ba623b88bc12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:54 +0200 Subject: [PATCH 05/20] docs(product): add feature-parity-policy --- docs/product/feature-parity-policy.md | 81 +++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/product/feature-parity-policy.md diff --git a/docs/product/feature-parity-policy.md b/docs/product/feature-parity-policy.md new file mode 100644 index 0000000..70a8e5a --- /dev/null +++ b/docs/product/feature-parity-policy.md @@ -0,0 +1,81 @@ +# Feature parity policy + +## Purpose + +Architectural consolidation should reduce code ownership without accidentally shrinking the product. This policy applies whenever a local implementation is removed, replaced, or moved upstream. + +Tracking: [#19](https://github.com/VPRamon/spod/issues/19). + +> **Remove duplicated implementation, not product capability.** + +## Three layers + +### Implementation + +A local file such as `src/io/sp3.rs` can disappear when Siderust provides the canonical parser. + +### Rust API compatibility + +An old namespace such as `spod::io::sp3::*` does not have to remain. Broad compatibility reexports are discouraged because they recreate ambiguous ownership. + +### Product capability + +A supported workflow being able to consume SP3 may still be a required product capability even after both the implementation and old namespace disappear. + +## Required classifications + +### KEEP IN SPOD + +Operational/application behavior such as job lifecycle, input resolution, mission profiles, processing baselines, QC thresholds, REST/CLI, and reprocessing. + +### MIGRATE TO SIDERUST + +The feature remains available to workflows, but the reusable implementation is canonical upstream. Typical examples are standard format parsing, observation models, estimators, and product serialization. + +### UPSTREAM GAP FIRST + +The product needs the capability but upstream does not yet provide equivalent semantics. The local implementation must not be deleted or silently degraded until the gap is resolved. + +Full Vallado-style SGP4/SDP4 is the current example; see [#29](https://github.com/VPRamon/spod/issues/29). + +### INTENTIONALLY RETIRE + +The capability does not belong in the target product and is deliberately removed. This requires rationale, impact assessment, changelog/documentation, and confirmation that no supported workflow depends on it. + +Lambert may become an example of this category, but that decision must be explicit. + +## Migration checklist + +Every deletion/replacement PR should answer: + +1. What user-visible capability existed? +2. Is it still part of the product? +3. Where will the implementation live? +4. Is the replacement semantically equivalent for the supported workflow? +5. Which product-level test proves the workflow still works? +6. Which algorithm/parser tests can move upstream? +7. Are dependencies/features removed only after the last product consumer migrates? +8. Does documentation describe ownership correctly? + +## Testing policy + +Tests that may move upstream include parser conformance, numerical verification, estimator kernels, SPICE segment evaluation, generic format round-trips, and generic SGP4 reference cases once upstream owns that backend. + +Tests that stay in `spod` include real workflow ingestion, configuration mapping, provenance, artifact generation, QC policy, unsupported-combination failures, CLI/REST parity, and end-to-end reference datasets. + +## No silent downgrade + +Compiling against Siderust is not enough. Differences in model, format subset, interpolation, physical corrections, deep-space support, or numerical precision must be evaluated against product requirements. + +## Review gate + +For #9-#13 and future consolidation work, unclassified capability loss is a blocker. + +The desired result is: + +```text +less duplicated code ++ same or better product capability ++ clearer ownership ++ stronger operational tests +``` \ No newline at end of file From 3014b36bb80bcd590e556fa2b6fe4c3b1105440c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:56 +0200 Subject: [PATCH 06/20] docs(product): add commercial-model --- docs/product/commercial-model.md | 111 +++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/product/commercial-model.md diff --git a/docs/product/commercial-model.md b/docs/product/commercial-model.md new file mode 100644 index 0000000..6d98136 --- /dev/null +++ b/docs/product/commercial-model.md @@ -0,0 +1,111 @@ +# Commercial model and packaging + +This page describes plausible ways to package `spod`. It is directional, not a pricing commitment. + +## Product thesis + +The commercial object is not the scientific algorithm itself. The value is supported POD workflows, operational reliability, integration, reproducibility, quality reporting, deployment, and controlled upgrades. + +## spod Engine + +Self-hosted operational POD service for customers who need to run inside their own infrastructure. + +Expected surfaces: + +- container image; +- CLI; +- REST API; +- mission profiles; +- artifact integration; +- metrics/logging; +- supported releases and onboarding. + +Likely customers include satellite operators, ground-segment integrators, institutional missions, and organizations with data-residency requirements. + +## spod Validate + +Independent orbit-quality and processing-validation product that can be used even when `spod` is not the primary POD engine. + +Core capabilities: + +- orbit-vs-reference comparison; +- RTN/RAC statistics; +- residual assessment when available; +- SLR validation when available; +- processing-baseline comparison; +- machine-readable quality status; +- audit report. + +Tracked by [#24](https://github.com/VPRamon/spod/issues/24). + +This may have lower adoption friction because the customer does not need to replace its operational POD chain. + +## spod Cloud + +Managed POD execution where a customer submits or streams tracking data and obtains products through an API. + +Additional requirements beyond Engine include durable storage, tenancy, auth, usage accounting, durable queues, SLOs, and security/compliance. These are not immediate repository goals. + +## Deployment modes + +```text +local CLI + | +container + | +customer REST service + | +managed cloud service +``` + +Scientific behavior should not fork by deployment mode. + +## Commercial readiness gates + +### Gate 1 - Engineering reference + +- deterministic synthetic workflow; +- provenance; +- CI; +- CLI/REST/container. + +### Gate 2 - Real-data product proof + +- onboard GNSS workflow; +- real standard datasets; +- standard orbit products; +- operational QC; +- documented validation case. + +This is the critical transition represented by [#20](https://github.com/VPRamon/spod/issues/20). + +### Gate 3 - Operational pilot + +- mission profiles; +- dataset resolution; +- stable API; +- structured errors; +- observability; +- repeated daily operation on a representative mission. + +### Gate 4 - Production deployment + +- controlled upgrades; +- run/campaign recovery; +- resource sizing; +- support procedures; +- security review; +- sufficient external validation for the target accuracy class. + +### Gate 5 - Scale + +- fleet orchestration; +- reprocessing campaigns; +- multiple latency classes; +- operational dashboards/alerts. + +## Possible charging models + +Potential packaging could support annual self-hosted license/support, managed service per spacecraft/run, mission onboarding, and validation/commissioning packages. + +Commercial value should come from operational product quality rather than duplicating scientific code that belongs in Siderust. \ No newline at end of file From 0c1fd3f5100827f1616bda253ed2fc6b6edad8b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:34:58 +0200 Subject: [PATCH 07/20] docs(product): add commercial-roadmap --- docs/product/commercial-roadmap.md | 73 ++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/product/commercial-roadmap.md diff --git a/docs/product/commercial-roadmap.md b/docs/product/commercial-roadmap.md new file mode 100644 index 0000000..14178b6 --- /dev/null +++ b/docs/product/commercial-roadmap.md @@ -0,0 +1,73 @@ +# Product roadmap + +This roadmap sequences work by commercial/product dependency rather than by code-module cleanup alone. + +## Phase 0 - Protect capability during consolidation + +Goal: reduce duplicated code without losing product features. + +- [#19](https://github.com/VPRamon/spod/issues/19) product capability parity +- [#9](https://github.com/VPRamon/spod/issues/9) format/orbital-mechanics consolidation under the parity rule +- [#29](https://github.com/VPRamon/spod/issues/29) preserve full SGP4/SDP4 semantics +- existing architecture issues #10-#13 continue after product capabilities are classified + +Exit criterion: every major current capability is KEEP, MIGRATE, UPSTREAM GAP FIRST, or INTENTIONALLY RETIRE. + +## Phase 1 - Make the service coherent + +Goal: one operational application layer over Siderust. + +- consolidate service orchestration (#10); +- unify CLI/REST on the same job model (#11); +- rebuild integration/CI around service behavior (#12); +- make documentation/metadata match the product (#13). + +Exit criterion: service concepts rather than scientific modules define the public surface. + +## Phase 2 - Build the North Star product + +Goal: real onboard-GNSS data to precise orbit product. + +- [#20](https://github.com/VPRamon/spod/issues/20) real GNSS POD workflow +- [#21](https://github.com/VPRamon/spod/issues/21) dataset resolution/acquisition +- [#22](https://github.com/VPRamon/spod/issues/22) mission profiles +- [#23](https://github.com/VPRamon/spod/issues/23) operational QC/run health +- [#28](https://github.com/VPRamon/spod/issues/28) stable product/artifact API + +Exit criterion: a representative LEO mission can run repeatedly from real tracking data and produce standard products, QC, and provenance. + +## Phase 3 - Prove value around the core + +Goal: useful commercial workflows that do not require replacing the customer's full operations stack. + +- [#24](https://github.com/VPRamon/spod/issues/24) independent orbit validation +- [#30](https://github.com/VPRamon/spod/issues/30) mission commissioning + +Exit criterion: `spod Validate`/commissioning can produce actionable reports on representative external datasets. + +## Phase 4 - Operational scale + +Goal: make the product suitable for repeated mission/fleet operations. + +- [#25](https://github.com/VPRamon/spod/issues/25) historical reprocessing +- [#26](https://github.com/VPRamon/spod/issues/26) latency classes +- [#27](https://github.com/VPRamon/spod/issues/27) observability +- [#31](https://github.com/VPRamon/spod/issues/31) fleet/constellation orchestration + +Exit criterion: many jobs can be operated, inspected, retried, compared, and summarized without bespoke shell automation. + +## Product metrics + +Useful future metrics include: + +- successful run rate; +- percentage of runs requiring manual intervention; +- median and tail processing latency; +- percentage of runs with complete provenance; +- QC pass/warning/fail distribution; +- input-resolution failure rate; +- reprocessing resume success; +- fleet processing completion rate; +- API/job stability across releases. + +Scientific accuracy metrics remain mission/workflow specific and should be defined by mission profiles and validation requirements. \ No newline at end of file From dcaa8a233e1ed8cd5a3acf3c863f0e1e7ebeb86f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:35:51 +0200 Subject: [PATCH 08/20] docs(product): add README --- docs/product/use-cases/README.md | 37 ++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/product/use-cases/README.md diff --git a/docs/product/use-cases/README.md b/docs/product/use-cases/README.md new file mode 100644 index 0000000..a71b647 --- /dev/null +++ b/docs/product/use-cases/README.md @@ -0,0 +1,37 @@ +# Product use cases + +These use cases define the workflows `spod` should productize. They are deliberately written from the operator/customer perspective rather than from the module/API perspective. + +Each use case separates: + +- customer problem; +- inputs; +- `spod` responsibilities; +- Siderust responsibilities; +- outputs; +- operational quality criteria; +- MVP scope; +- related roadmap issues. + +## Use-case index + +| Use case | Core value | Tracking | +|---|---|---| +| [Operational onboard-GNSS POD](operational-gnss-pod.md) | precise LEO orbit products from tracking data | [#20](https://github.com/VPRamon/spod/issues/20) | +| [Fleet / constellation POD](fleet-constellation-pod.md) | repeatable multi-spacecraft operations | [#31](https://github.com/VPRamon/spod/issues/31) | +| [Independent orbit validation](independent-orbit-validation.md) | objective quality assessment of an orbit solution | [#24](https://github.com/VPRamon/spod/issues/24) | +| [Mission commissioning](mission-commissioning.md) | prove GNSS/POD chain health after launch/change | [#30](https://github.com/VPRamon/spod/issues/30) | +| [Historical reprocessing](historical-reprocessing.md) | reproducible processing baselines over long periods | [#25](https://github.com/VPRamon/spod/issues/25) | +| [Rapid/final latency classes](latency-classes.md) | explicit timeliness/quality operating modes | [#26](https://github.com/VPRamon/spod/issues/26) | + +## Shared foundation + +All use cases should rely on the same platform capabilities: + +- [#21](https://github.com/VPRamon/spod/issues/21) dataset resolution; +- [#22](https://github.com/VPRamon/spod/issues/22) mission profiles; +- [#23](https://github.com/VPRamon/spod/issues/23) operational QC; +- [#27](https://github.com/VPRamon/spod/issues/27) observability; +- [#28](https://github.com/VPRamon/spod/issues/28) product/artifact API. + +Scientific primitives should be consumed from Siderust under the [feature parity policy](../feature-parity-policy.md). \ No newline at end of file From eb2bf369c6de99b96e8f6778ea751c2e1ed83102 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:35:53 +0200 Subject: [PATCH 09/20] docs(product): add operational-gnss-pod --- .../product/use-cases/operational-gnss-pod.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/product/use-cases/operational-gnss-pod.md diff --git a/docs/product/use-cases/operational-gnss-pod.md b/docs/product/use-cases/operational-gnss-pod.md new file mode 100644 index 0000000..e387593 --- /dev/null +++ b/docs/product/use-cases/operational-gnss-pod.md @@ -0,0 +1,107 @@ +# Use case: Operational onboard-GNSS POD + +## Customer + +LEO/Earth-observation operator or ground-segment integrator. + +## Problem + +The spacecraft produces onboard GNSS observations. The operator needs precise orbit products with known quality and provenance, but does not want to assemble and maintain a bespoke stack of parsers, force models, estimators, QC scripts, and product writers. + +## Trigger + +A new observation arc is available for processing. + +## Inputs + +Typical input contract: + +- onboard GNSS observations (for example RINEX); +- precise GNSS orbit/clock products as required; +- antenna calibration; +- EOP; +- mission profile / spacecraft metadata; +- arc start/end; +- processing/estimation policy. + +Dataset acquisition may be explicit initially and progressively automated by [#21](https://github.com/VPRamon/spod/issues/21). + +## spod responsibilities + +- validate the request and mission profile; +- resolve concrete input datasets; +- check availability/coverage and hash inputs; +- translate supported configuration into a Siderust POD problem; +- run the supported estimation workflow; +- apply operational QC policy; +- write and index artifacts; +- report status/errors; +- preserve complete provenance; +- expose the same job through CLI and REST. + +## Siderust responsibilities + +- standard format parsing; +- dynamics/force models; +- propagation/variational equations; +- GNSS observation models; +- estimation kernels; +- reusable QC primitives; +- standard product serialization. + +## Outputs + +At minimum: + +```text +run.manifest.json +products/orbit.sp3 +products/orbit.oem +residuals/residuals.csv +qc/qc.json +``` + +Future outputs may include covariance/uncertainty and additional product formats. + +## Operator result + +A successful run should answer both: + +1. Did the job execute? +2. Is the resulting orbit operationally acceptable? + +Execution success and quality success are separate concepts. + +## Quality indicators + +Possible indicators include: + +- estimator convergence; +- accepted/rejected observation count; +- code/carrier residual statistics; +- reduced chi-square; +- covariance/uncertainty when available; +- orbit continuity; +- reference-orbit comparison when configured; +- SLR validation when configured; +- completeness of required inputs. + +Thresholds belong in mission/workflow policy, not in generic Siderust kernels. + +## Failure modes + +`spod` should distinguish at least: + +- invalid configuration; +- unavailable input dataset; +- unsupported data/model; +- parse/coverage failure; +- scientific convergence failure; +- artifact publication failure; +- completed run that fails operational QC. + +## MVP + +The MVP is complete when one representative real LEO dataset can run end to end repeatedly and produce standard orbit products, residuals, QC, and complete provenance through the same service API used by CLI/REST. + +Tracking: [#20](https://github.com/VPRamon/spod/issues/20). \ No newline at end of file From 3c83925169444428f965e800cc6036bf1b6602e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:35:56 +0200 Subject: [PATCH 10/20] docs(product): add fleet-constellation-pod --- .../use-cases/fleet-constellation-pod.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/product/use-cases/fleet-constellation-pod.md diff --git a/docs/product/use-cases/fleet-constellation-pod.md b/docs/product/use-cases/fleet-constellation-pod.md new file mode 100644 index 0000000..12f7c48 --- /dev/null +++ b/docs/product/use-cases/fleet-constellation-pod.md @@ -0,0 +1,57 @@ +# Use case: Fleet / constellation POD + +## Customer + +Operator of many similar LEO spacecraft. + +## Problem + +A single-spacecraft POD script does not scale to tens or hundreds of spacecraft. Configuration drifts, failures need isolated retries, and operators need both per-spacecraft and fleet-level visibility. + +## Trigger + +A processing cycle, data arrival, or scheduled campaign requires POD runs for a set of spacecraft/arcs. + +## Inputs + +- fleet definition; +- spacecraft membership; +- mission profile/version per spacecraft; +- time/arc selector; +- processing class; +- concurrency/retry policy. + +## spod responsibilities + +- expand a fleet request deterministically into individual POD jobs; +- preserve each job as an independent reproducible run; +- control concurrency and retries; +- expose fleet and per-spacecraft status; +- aggregate QC without hiding individual results; +- support safe processing-baseline rollout. + +## Siderust responsibilities + +None of the fleet logic belongs in Siderust. Each spacecraft job consumes the same reusable Siderust scientific engine as a single run. + +## Outputs + +- per-spacecraft run artifacts and manifests; +- fleet/campaign manifest; +- aggregate success/failure summary; +- fleet QC summary; +- retryable list of failed or blocked jobs. + +## Operational requirements + +- one failing spacecraft must not invalidate successful runs for others; +- retries should be idempotent; +- fleet status must not require parsing filesystem state; +- configuration version must be visible per spacecraft; +- high-cardinality telemetry must be designed carefully. + +## MVP + +A fleet definition with multiple spacecraft expands into deterministic jobs, executes using the common service runner, and produces an aggregate status/QC summary. + +Tracking: [#31](https://github.com/VPRamon/spod/issues/31). \ No newline at end of file From fe7c878dd816e2b16f791891739b1506a6e82181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:35:58 +0200 Subject: [PATCH 11/20] docs(product): add independent-orbit-validation --- .../use-cases/independent-orbit-validation.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/product/use-cases/independent-orbit-validation.md diff --git a/docs/product/use-cases/independent-orbit-validation.md b/docs/product/use-cases/independent-orbit-validation.md new file mode 100644 index 0000000..d835177 --- /dev/null +++ b/docs/product/use-cases/independent-orbit-validation.md @@ -0,0 +1,65 @@ +# Use case: Independent orbit validation + +## Customer + +Satellite operator, ground-segment integrator, mission acceptance team, or external validation provider. + +## Problem + +The customer already has an operational orbit solution but needs independent evidence of accuracy, continuity, or regression after a processing/software change. + +## Product opportunity + +This use case can deliver commercial value without requiring the customer to replace its primary POD engine. + +## Inputs + +- candidate orbit product; +- independent/reference orbit product; +- optional observations/residual data; +- optional SLR data; +- validation profile/thresholds. + +## spod responsibilities + +- validate/resolve input products; +- align comparable intervals/epochs; +- orchestrate canonical orbit-comparison/QC primitives; +- apply service-level thresholds; +- produce machine-readable and human-readable findings; +- preserve provenance for both solutions. + +## Core metrics + +Where scientifically valid and supported: + +- 3D RMS; +- radial / along-track / cross-track RMS; +- maxima/percentiles; +- coverage/gaps; +- time-series differences; +- residual/SLR statistics when provided. + +## Output example + +```text +overall PASS +3D RMS 0.028 m +radial RMS 0.009 m +along-track RMS 0.021 m +cross-track RMS 0.015 m +coverage PASS +SLR validation NOT_RUN +``` + +The exact thresholds are profile-specific. + +## Failure/quality semantics + +A technically successful comparison may still return WARNING/FAIL because the candidate orbit exceeds configured quality gates. + +## MVP + +Compare two supported standard orbit products end to end, report RTN/RAC-style statistics where appropriate, generate a reproducible report, and expose it through the common service layer. + +Tracking: [#24](https://github.com/VPRamon/spod/issues/24). \ No newline at end of file From 30a81b324343bda04f2d0338fcdbc07c789ab083 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:36:00 +0200 Subject: [PATCH 12/20] docs(product): add mission-commissioning --- .../use-cases/mission-commissioning.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/product/use-cases/mission-commissioning.md diff --git a/docs/product/use-cases/mission-commissioning.md b/docs/product/use-cases/mission-commissioning.md new file mode 100644 index 0000000..d2b90d3 --- /dev/null +++ b/docs/product/use-cases/mission-commissioning.md @@ -0,0 +1,62 @@ +# Use case: Mission commissioning + +## Customer + +Mission operations, flight-dynamics, and ground-segment teams during early operations or after major receiver/processing changes. + +## Problem + +Early mission data can reveal unexpected GNSS availability, timing, receiver clock, metadata, antenna, or processing issues. Teams need a systematic way to determine whether the POD chain is operational. + +## Trigger + +- launch/early orbit phase; +- GNSS receiver/configuration change; +- antenna/CoM metadata update; +- major ground-processing upgrade; +- anomaly investigation. + +## Inputs + +- onboard GNSS observations; +- mission profile; +- supporting GNSS/EOP/antenna products; +- optional onboard navigation solution; +- optional external precise orbit; +- optional SLR observations. + +## spod responsibilities + +- run the supported POD workflow; +- assess data availability and gaps; +- summarize accepted/rejected observations; +- assess time/clock behavior where available; +- evaluate residuals and convergence; +- compare against external/onboard orbit when configured; +- apply commissioning acceptance criteria; +- produce a reproducible report. + +## Example findings + +```text +GNSS availability PASS +time tags PASS +receiver clock WARNING +carrier residuals PASS +orbit convergence PASS +external orbit compare PASS +SLR validation NOT_RUN +``` + +## Output + +- normal run products; +- commissioning report; +- issue/finding list with severity and reason; +- complete input/config provenance. + +## MVP + +A representative commissioning dataset can be processed through the common service and produce actionable PASS/WARNING/FAIL findings without bespoke analysis scripts. + +Tracking: [#30](https://github.com/VPRamon/spod/issues/30). \ No newline at end of file From 6160a41e6d4a93f1c5d6777f99253f205be6c005 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:36:02 +0200 Subject: [PATCH 13/20] docs(product): add historical-reprocessing --- .../use-cases/historical-reprocessing.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/product/use-cases/historical-reprocessing.md diff --git a/docs/product/use-cases/historical-reprocessing.md b/docs/product/use-cases/historical-reprocessing.md new file mode 100644 index 0000000..718c6d9 --- /dev/null +++ b/docs/product/use-cases/historical-reprocessing.md @@ -0,0 +1,54 @@ +# Use case: Historical reprocessing + +## Customer + +Science-processing team, operator, or mission ground segment. + +## Problem + +Improved models, calibration products, reference data, or software versions require historical orbit products to be regenerated. Ad-hoc loops are difficult to resume, audit, and compare. + +## Product concepts + +- processing baseline; +- mission-profile version; +- software/Siderust version; +- date/arc range; +- input-data policy; +- campaign manifest; +- per-run status; +- campaign-level QC. + +## Trigger + +A new baseline is approved or a historical correction requires regeneration of a period. + +## Example + +```text +spod reprocess \ + --mission my-leo \ + --from 2026-01-01 \ + --to 2026-06-30 \ + --baseline pod-v3 +``` + +## spod responsibilities + +- expand the campaign deterministically into jobs; +- resolve baseline-specific inputs; +- execute/retry individual jobs; +- skip/reuse already completed compatible runs where policy permits; +- aggregate status and QC; +- preserve provenance per job and for the campaign; +- enable old/new baseline comparison. + +## Siderust responsibilities + +Scientific execution remains identical to normal POD runs. Campaign orchestration does not belong in Siderust. + +## MVP + +A date/arc range expands into deterministic jobs, interrupted execution can resume, and a campaign summary reports completion and QC without recomputing all successful jobs. + +Tracking: [#25](https://github.com/VPRamon/spod/issues/25). \ No newline at end of file From ce77b4944955b6e3a6f93ef27f031f9e8afa00c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:36:04 +0200 Subject: [PATCH 14/20] docs(product): add latency-classes --- docs/product/use-cases/latency-classes.md | 50 +++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/product/use-cases/latency-classes.md diff --git a/docs/product/use-cases/latency-classes.md b/docs/product/use-cases/latency-classes.md new file mode 100644 index 0000000..a0b25ae --- /dev/null +++ b/docs/product/use-cases/latency-classes.md @@ -0,0 +1,50 @@ +# Use case: Rapid and final processing classes + +## Customer + +Operational ground segment that needs different trade-offs between timeliness and supporting-product quality. + +## Problem + +Not every orbit product is generated under the same data-availability constraints. A service needs explicit processing policies rather than hidden fallback behavior. + +## Product concept + +A job declares a processing/latency class. The class controls service policy such as: + +- which supporting products are acceptable; +- whether the service waits for a preferred product; +- allowed fallbacks; +- priority; +- retry/wait behavior; +- publication state; +- QC expectations. + +Example conceptual classes: + +```text +rapid +routine +final +``` + +Names and timing targets should remain configurable rather than hard-coded. + +## spod responsibilities + +- represent the class in job configuration; +- map it to dataset-resolution policy; +- make waits/fallbacks explicit; +- record the chosen class and actual concrete inputs in provenance; +- distinguish waiting-for-input from scientific execution; +- expose latency/status metrics. + +## Siderust responsibilities + +None of the scheduling/input-availability policy belongs in the scientific engine. + +## MVP + +At least two classes select different input-resolution policies, with deterministic fallback/error behavior and integration coverage. + +Tracking: [#26](https://github.com/VPRamon/spod/issues/26). \ No newline at end of file From 96a93e6e0df8ccb325d1e3d81388fafb28540ff4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:36:45 +0200 Subject: [PATCH 15/20] docs: link product wiki from README --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 5726bb5..4be3423 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,12 @@ cd spod cargo test ``` +## Product wiki + +The product definition, commercial positioning, capability ownership, feature-parity policy, roadmap, and detailed operational use cases live in the [product wiki](docs/product/README.md). + +The product North Star is **onboard GNSS observations -> automated precise LEO orbit + QC + standard products + full provenance**. + ## Relationship with the Siderust ecosystem Foundational astrodynamics, typed quantities, time scales, frames, and reusable numerical mechanics live in the released Siderust ecosystem crates. `spod` is built on top of `siderust::pod`; it does not expose a scientific compatibility facade. Callers needing reusable force, observation, estimation, QC, or product APIs should import Siderust directly. From aab8a0323c73c496604e6a241b21ffb3db281bbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:37:41 +0200 Subject: [PATCH 16/20] docs(product): avoid obsolete namespace examples --- docs/product/capability-map.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product/capability-map.md b/docs/product/capability-map.md index 7194088..15a007b 100644 --- a/docs/product/capability-map.md +++ b/docs/product/capability-map.md @@ -73,7 +73,7 @@ Campaign Fleet ``` -and less like a second scientific namespace such as `spod::forces`, `spod::estimation`, `spod::tle`, `spod::spice`, or `spod::lambert`. +and less like a second namespace of generic force models, estimators, standard-format parsers, SPICE internals, or mission-design algorithms. ## Important distinction From 47bd906db4abd1ca00b8ab5a147f2b852cfcbfc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:54:21 +0200 Subject: [PATCH 17/20] docs(product): refine capability-map after capability audit --- docs/product/capability-map.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/product/capability-map.md b/docs/product/capability-map.md index 15a007b..daa2b91 100644 --- a/docs/product/capability-map.md +++ b/docs/product/capability-map.md @@ -7,7 +7,8 @@ This document maps product capabilities to their intended long-term owner. The d - **KEEP IN SPOD** - service/application capability. - **MIGRATE TO SIDERUST** - product capability remains, implementation becomes canonical upstream. - **UPSTREAM GAP FIRST** - capability must not be deleted until upstream has required semantics. -- **DECISION REQUIRED** - explicit product decision needed. +- **INTENTIONALLY RETIRE** - capability is deliberately not part of the core product. +- **REFERENCE EXAMPLE** - mission-specific capability demonstrated outside the core product surface. - **ADD TO SPOD** - missing product/application capability. ## Existing capabilities @@ -22,21 +23,25 @@ This document maps product capabilities to their intended long-term owner. The d | REST API | core interface | spod | KEEP IN SPOD | | Docker/deployment | operations | spod | KEEP IN SPOD | | Synthetic reference workflow | integration/reference | spod + Siderust | KEEP IN SPOD | +| Human-readable QC report | product presentation/artifact | spod | KEEP IN SPOD / RESTORE - [#33](https://github.com/VPRamon/spod/issues/33) | | Force models | scientific primitive | Siderust | MIGRATE TO SIDERUST | | Propagation / STM | scientific primitive | Siderust | MIGRATE TO SIDERUST | -| WLS / nonlinear estimation | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| WLS / nonlinear / sequential estimation | scientific primitive | Siderust | MIGRATE TO SIDERUST | | Observation models | scientific primitive | Siderust | MIGRATE TO SIDERUST | -| Generic QC statistics | scientific primitive | Siderust | MIGRATE TO SIDERUST | +| Generic QC statistics, orbit comparison, SLR validation | scientific primitive | Siderust | MIGRATE TO SIDERUST; expose through spod workflows | | SP3/OEM serialization | standard product primitive | Siderust | MIGRATE TO SIDERUST | +| Run-manifest JSON schema | reusable run contract | Siderust | MIGRATE TO SIDERUST; canonical schema already exists upstream | | TLE / 3LE / OMM | standard formats | Siderust | MIGRATE TO SIDERUST | | SP3 / RINEX / ANTEX / SINEX / ORBEX | standard formats | Siderust | MIGRATE TO SIDERUST | | EOP / CRD / CPF / OEM / OPM / TDM | standard formats | Siderust | MIGRATE TO SIDERUST | | SPICE / SPK | scientific/format primitive | Siderust | MIGRATE TO SIDERUST | | Full Vallado SGP4/SDP4 | useful operational capability | canonical Siderust ecosystem backend | UPSTREAM GAP FIRST - [#29](https://github.com/VPRamon/spod/issues/29) | -| Lambert solver | generic mission-design function | ecosystem | DECISION REQUIRED | -| LISA-specific functionality | mission-specific | TBD | DECISION REQUIRED | -| DORIS workflow | potential POD workflow | spod + Siderust | DECISION REQUIRED / likely future | -| Parquet export | product/export capability | Siderust serializer + spod policy | KEEP if used by supported workflows | +| Lambert solver | generic mission-design function | ecosystem | INTENTIONALLY RETIRE from core spod unless a concrete operational workflow is justified | +| LISA-specific functionality | mission-specific reference | example/reference layer | REFERENCE EXAMPLE - [#34](https://github.com/VPRamon/spod/issues/34) | +| DORIS parser | standard format | Siderust | MIGRATE TO SIDERUST; not a spod feature by itself | +| DORIS POD workflow | mission/product workflow | spod + Siderust | future product decision | +| de440 feature | validation/development mechanism | tests/upstream | not a product capability | +| Parquet export | optional artifact format | Siderust serializer + spod policy | KEEP only when exposed by a supported workflow | ## Missing product capabilities @@ -46,13 +51,15 @@ This document maps product capabilities to their intended long-term owner. The d | Dataset resolution/acquisition | operational orchestration | [#21](https://github.com/VPRamon/spod/issues/21) | | Versioned mission profiles | application configuration | [#22](https://github.com/VPRamon/spod/issues/22) | | Operational QC / run health | service policy | [#23](https://github.com/VPRamon/spod/issues/23) | -| Independent orbit validation | product workflow | [#24](https://github.com/VPRamon/spod/issues/24) | +| Independent orbit/SLR validation | product workflow | [#24](https://github.com/VPRamon/spod/issues/24) | +| Human-readable QC artifact | application/reporting | [#33](https://github.com/VPRamon/spod/issues/33) | | Reprocessing campaigns | orchestration | [#25](https://github.com/VPRamon/spod/issues/25) | | Latency/processing classes | operational policy | [#26](https://github.com/VPRamon/spod/issues/26) | | Metrics / observability | operations | [#27](https://github.com/VPRamon/spod/issues/27) | | Stable product/artifact API | service interface | [#28](https://github.com/VPRamon/spod/issues/28) | | Mission commissioning | product workflow | [#30](https://github.com/VPRamon/spod/issues/30) | | Fleet/constellation orchestration | scale/operations | [#31](https://github.com/VPRamon/spod/issues/31) | +| LISA reference example | extension/reference use case | [#34](https://github.com/VPRamon/spod/issues/34) | ## Target public concept model @@ -77,4 +84,4 @@ and less like a second namespace of generic force models, estimators, standard-f ## Important distinction -Removing an old Rust API such as `spod::tle::parse_tle` does not imply removing the ability for a supported `spod` workflow to accept TLE data. The workflow should call `siderust::formats::tle` directly while preserving the product capability. \ No newline at end of file +Removing an old Rust API such as a local TLE parser does not imply removing the ability for a supported `spod` workflow to accept TLE data. The workflow should call the canonical Siderust implementation directly while preserving the product capability. From 703aeaefd9bb8b9d4b6c4748e4c09ef88fa15ffb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:54:23 +0200 Subject: [PATCH 18/20] docs(product): refine feature-parity-policy after capability audit --- docs/product/feature-parity-policy.md | 31 +++++++++++++++++---------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/product/feature-parity-policy.md b/docs/product/feature-parity-policy.md index 70a8e5a..6d44360 100644 --- a/docs/product/feature-parity-policy.md +++ b/docs/product/feature-parity-policy.md @@ -2,7 +2,7 @@ ## Purpose -Architectural consolidation should reduce code ownership without accidentally shrinking the product. This policy applies whenever a local implementation is removed, replaced, or moved upstream. +Architectural consolidation should reduce code ownership without accidentally shrinking the product. This policy applies whenever a local implementation is removed, replaced, moved upstream, or reclassified as a reference example. Tracking: [#19](https://github.com/VPRamon/spod/issues/19). @@ -12,25 +12,25 @@ Tracking: [#19](https://github.com/VPRamon/spod/issues/19). ### Implementation -A local file such as `src/io/sp3.rs` can disappear when Siderust provides the canonical parser. +A local parser or scientific algorithm can disappear when Siderust provides the canonical implementation. ### Rust API compatibility -An old namespace such as `spod::io::sp3::*` does not have to remain. Broad compatibility reexports are discouraged because they recreate ambiguous ownership. +An old module path does not have to remain. Broad compatibility reexports are discouraged because they recreate ambiguous ownership. ### Product capability -A supported workflow being able to consume SP3 may still be a required product capability even after both the implementation and old namespace disappear. +A supported workflow being able to consume a format, run a validation, or produce an artifact may remain required even after the local implementation and old namespace disappear. ## Required classifications ### KEEP IN SPOD -Operational/application behavior such as job lifecycle, input resolution, mission profiles, processing baselines, QC thresholds, REST/CLI, and reprocessing. +Operational/application behavior such as job lifecycle, input resolution, mission profiles, processing baselines, QC policy, human-readable reporting, REST/CLI, and reprocessing. ### MIGRATE TO SIDERUST -The feature remains available to workflows, but the reusable implementation is canonical upstream. Typical examples are standard format parsing, observation models, estimators, and product serialization. +The capability remains available to workflows, but the reusable implementation is canonical upstream. Typical examples are standard format parsing, observation models, estimators, orbit comparison, SLR validation primitives, and product serialization. ### UPSTREAM GAP FIRST @@ -42,26 +42,35 @@ Full Vallado-style SGP4/SDP4 is the current example; see [#29](https://github.co The capability does not belong in the target product and is deliberately removed. This requires rationale, impact assessment, changelog/documentation, and confirmation that no supported workflow depends on it. -Lambert may become an example of this category, but that decision must be explicit. +Lambert is currently classified this way for the core POD service unless a concrete operational use case changes that decision. + +### REFERENCE EXAMPLE + +Some mission-specific functionality is valuable as a demonstration of extensibility but should not become permanent core API or Cargo-feature surface. + +LISA is the current example; see [#34](https://github.com/VPRamon/spod/issues/34). ## Migration checklist Every deletion/replacement PR should answer: 1. What user-visible capability existed? -2. Is it still part of the product? -3. Where will the implementation live? +2. Is it still part of the core product, a reference example, or intentionally retired? +3. Where will the reusable implementation live? 4. Is the replacement semantically equivalent for the supported workflow? 5. Which product-level test proves the workflow still works? 6. Which algorithm/parser tests can move upstream? 7. Are dependencies/features removed only after the last product consumer migrates? 8. Does documentation describe ownership correctly? +9. Did any presentation/reporting/application logic get swept away together with scientific code? ## Testing policy Tests that may move upstream include parser conformance, numerical verification, estimator kernels, SPICE segment evaluation, generic format round-trips, and generic SGP4 reference cases once upstream owns that backend. -Tests that stay in `spod` include real workflow ingestion, configuration mapping, provenance, artifact generation, QC policy, unsupported-combination failures, CLI/REST parity, and end-to-end reference datasets. +Tests that stay in `spod` include real workflow ingestion, configuration mapping, provenance, artifact/report generation, QC policy, unsupported-combination failures, CLI/REST parity, and end-to-end reference datasets. + +Reference examples may carry small deterministic integration tests without becoming core product features. ## No silent downgrade @@ -78,4 +87,4 @@ less duplicated code + same or better product capability + clearer ownership + stronger operational tests -``` \ No newline at end of file +``` From 6e265fde985d2163536cf089dd5a2aca4e82dedb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:54:25 +0200 Subject: [PATCH 19/20] docs(product): refine commercial-roadmap after capability audit --- docs/product/commercial-roadmap.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/product/commercial-roadmap.md b/docs/product/commercial-roadmap.md index 14178b6..ef739a8 100644 --- a/docs/product/commercial-roadmap.md +++ b/docs/product/commercial-roadmap.md @@ -2,16 +2,18 @@ This roadmap sequences work by commercial/product dependency rather than by code-module cleanup alone. -## Phase 0 - Protect capability during consolidation +## Phase 0 - Protect and recover capability during consolidation Goal: reduce duplicated code without losing product features. - [#19](https://github.com/VPRamon/spod/issues/19) product capability parity - [#9](https://github.com/VPRamon/spod/issues/9) format/orbital-mechanics consolidation under the parity rule - [#29](https://github.com/VPRamon/spod/issues/29) preserve full SGP4/SDP4 semantics -- existing architecture issues #10-#13 continue after product capabilities are classified +- [#33](https://github.com/VPRamon/spod/issues/33) restore service-owned human-readable QC reporting +- [#34](https://github.com/VPRamon/spod/issues/34) preserve LISA only as a reference/example use case +- existing architecture issues #10-#13 continue under the same product guardrails -Exit criterion: every major current capability is KEEP, MIGRATE, UPSTREAM GAP FIRST, or INTENTIONALLY RETIRE. +Exit criterion: every major current or recently removed capability is KEEP, MIGRATE, UPSTREAM GAP FIRST, INTENTIONALLY RETIRE, or REFERENCE EXAMPLE. ## Phase 1 - Make the service coherent @@ -34,13 +36,13 @@ Goal: real onboard-GNSS data to precise orbit product. - [#23](https://github.com/VPRamon/spod/issues/23) operational QC/run health - [#28](https://github.com/VPRamon/spod/issues/28) stable product/artifact API -Exit criterion: a representative LEO mission can run repeatedly from real tracking data and produce standard products, QC, and provenance. +Exit criterion: a representative LEO mission can run repeatedly from real tracking data and produce standard products, QC, provenance, and a useful human-readable report. ## Phase 3 - Prove value around the core Goal: useful commercial workflows that do not require replacing the customer's full operations stack. -- [#24](https://github.com/VPRamon/spod/issues/24) independent orbit validation +- [#24](https://github.com/VPRamon/spod/issues/24) independent orbit/SLR validation - [#30](https://github.com/VPRamon/spod/issues/30) mission commissioning Exit criterion: `spod Validate`/commissioning can produce actionable reports on representative external datasets. @@ -56,6 +58,10 @@ Goal: make the product suitable for repeated mission/fleet operations. Exit criterion: many jobs can be operated, inspected, retried, compared, and summarized without bespoke shell automation. +## Reference extensions + +Mission-specific demonstrations such as LISA can be maintained as examples that exercise the extension model without enlarging the core product surface. + ## Product metrics Useful future metrics include: @@ -70,4 +76,4 @@ Useful future metrics include: - fleet processing completion rate; - API/job stability across releases. -Scientific accuracy metrics remain mission/workflow specific and should be defined by mission profiles and validation requirements. \ No newline at end of file +Scientific accuracy metrics remain mission/workflow specific and should be defined by mission profiles and validation requirements. From b5fb6b7c1156deabf85536b4be2818c59bf73f9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vall=C3=A9s=20Puig=2C=20Ramon?= <74069811+VPRamon@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:54:28 +0200 Subject: [PATCH 20/20] docs(product): refine README after capability audit --- docs/product/README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/product/README.md b/docs/product/README.md index 9e453b1..0b61517 100644 --- a/docs/product/README.md +++ b/docs/product/README.md @@ -52,7 +52,7 @@ The North Star milestone is tracked in [#20](https://github.com/VPRamon/spod/iss - input resolution and acquisition policy; - orchestration of Siderust components; - artifact layout and publication; -- operational QC policy; +- operational QC policy and human-readable reporting; - provenance and reproducibility; - CLI and REST interfaces; - fleet/reprocessing orchestration; @@ -86,15 +86,17 @@ See [Feature parity policy](feature-parity-policy.md). | Historical reprocessing | Science / operations | Reproduce historical products under new baselines | [#25](https://github.com/VPRamon/spod/issues/25) | | Multi-latency operations | Operational ground segment | Rapid vs final processing policy | [#26](https://github.com/VPRamon/spod/issues/26) | -## Product enablers +## Product enablers and recovery work - product capability parity and migration discipline - [#19](https://github.com/VPRamon/spod/issues/19) - dataset resolution and acquisition - [#21](https://github.com/VPRamon/spod/issues/21) - mission profiles - [#22](https://github.com/VPRamon/spod/issues/22) - operational QC / run health - [#23](https://github.com/VPRamon/spod/issues/23) +- restore human-readable QC artifact - [#33](https://github.com/VPRamon/spod/issues/33) - observability - [#27](https://github.com/VPRamon/spod/issues/27) - stable product/artifact API - [#28](https://github.com/VPRamon/spod/issues/28) - SGP4/SDP4 parity preservation - [#29](https://github.com/VPRamon/spod/issues/29) +- LISA reference example rather than core feature - [#34](https://github.com/VPRamon/spod/issues/34) ## Product principles @@ -105,6 +107,7 @@ See [Feature parity policy](feature-parity-policy.md). 5. **Operational policy belongs in spod; reusable science belongs in Siderust.** 6. **Automation is a feature, not an external shell script.** 7. **Quality is an output.** A generated orbit is not enough; the service must explain whether it is fit for its configured operational purpose. +8. **Mission-specific demonstrations are examples unless they earn a core product use case.** ## Current status @@ -116,4 +119,4 @@ The key transition is: synthetic reference workflow -> real onboard GNSS data -> operational precise orbit product -``` \ No newline at end of file +```