Developer Tools Architecture

Verified against commit 942a18727c (2026-09-26, DOC-2 of SPRINT_20260926_001). Re-verify by reading the evidence paths listed in the Evidence section.

Audience: Stella Ops developers and operators working in local and CI workflows. For the module overview, see ./README.md. The operator CLI (stella) is a separate module: ../cli/architecture.md.

Overview

src/Tools/ contains independent utilities. Most are .NET console applications with their own Program.cs (several Policy tools are thin wrappers over the shared StellaOps.Policy.Tools library), several Bench harnesses are Python scripts, and the developer portal is a Node.js site. None is deployed as a service; each is invoked locally or in CI. No tool owns a database schema or exposes an HTTP endpoint.

Components

src/Tools/
  GoldenPairs/                  # Golden-pairs corpus tooling (StellaOps.Tools.GoldenPairs)
  PolicyDslValidator/           # Thin entry point over StellaOps.Policy.Tools
  PolicySchemaExporter/         # Thin entry point over StellaOps.Policy.Tools
  PolicySimulationSmoke/        # Thin entry point over StellaOps.Policy.Tools
  LanguageAnalyzerSmoke/        # Scanner language-analyzer golden-snapshot smoke checks
  NotifySmokeCheck/             # Valkey/Redis event stream + Notify deliveries smoke check
  RustFsMigrator/               # S3-compatible bucket -> RustFS object copy
  StellaOps.OpenApi.DocGen/     # OpenAPI spec -> Markdown API reference
  StellaOps.Bench/              # Performance harnesses (.NET and Python)
    LinkNotMerge/ LinkNotMerge.Vex/ Notify/ PolicyEngine/ Scanner.Analyzers/   # .NET
    ImpactIndex/ PolicyCache/ PolicyDelta/ Signals/ Determinism/ Graph/        # Python (+ Node UI driver)
  Bench/                        # Developer-only stella-vs-trivy compute/oracle/orchestration layer
    StellaOps.Bench.Compute/ StellaOps.Bench.Compute.Cli/ StellaOps.Bench.Compute.Orchestration/
    StellaOps.Bench.Oracle/ StellaOps.Bench.Oracle.Cli/ StellaOps.Bench.{Compute,Oracle}.Tests/
  StellaOps.Verifier/           # Standalone offline evidence-bundle verifier (stella-verifier)
  StellaOps.Tools.TlptScoper/   # DORA TLPT scope generator (Fixtures/, __Tests/)
  StellaOps.Sdk.Generator/      # go/ java/ python/ ts/ postprocess/, toolchain.lock.yaml
  StellaOps.DevPortal.Site/     # Astro/Starlight developer portal
  __Tests/                      # Per-tool test projects
  openssl/linux-x64/            # Vendored OpenSSL binaries
  certbund_offline_snapshot.py  # Offline CERT-Bund advisory snapshot helper
src/__Tests/supply-chain/       # Supply-chain hardening lanes (01..05)

Tool descriptions

GoldenPairs

StellaOps.Tools.GoldenPairs manages the golden-pairs corpus under src/__Tests/__Datasets/golden-pairs. Subcommands: mirror, diff, validate, with --repo-root and --dataset-root options.

PolicyDslValidator, PolicySchemaExporter, PolicySimulationSmoke

Thin entry points over StellaOps.Policy.Tools (PolicyDslValidatorApp, PolicySchemaExporterApp, PolicySimulationSmokeApp). The validator checks policy DSL files; the exporter writes the policy JSON schema; the simulation smoke check evaluates frozen scenario.json fixtures in-process (default root docs/samples/policy/simulations) against the StellaOps.Policy library, with a fixed evaluation time. None of them calls a running service.

LanguageAnalyzerSmoke

Runs the Scanner language analyzers in-process against curated fixtures and compares the serialized output to a golden expected.json for byte equality. Options: --repo-root, --analyzer, --plugin-directory, --fixture-path, --allow-golden-drift (mismatch becomes a warning) and --fixed-time.

NotifySmokeCheck

Reads the Valkey/Redis event stream (NOTIFY_SMOKE_REDIS_DSN, NOTIFY_SMOKE_STREAM) for the expected event kinds (NOTIFY_SMOKE_EXPECT_KINDS) within a lookback window (NOTIFY_SMOKE_LOOKBACK_MINUTES), then queries Notify deliveries at NOTIFY_SMOKE_NOTIFY_BASEURL with NOTIFY_SMOKE_NOTIFY_TOKEN and NOTIFY_SMOKE_NOTIFY_TENANT. Retries, page sizes and timeouts have their own NOTIFY_SMOKE_* variables.

RustFsMigrator

Copies objects from an S3-compatible source bucket (AWSSDK.S3) into RustFS with HTTP PUT. Options: --s3-bucket, --rustfs-endpoint, --rustfs-bucket (required), --prefix, --immutable, --retain-days, --dry-run. Transient failures are retried with exponential backoff.

StellaOps.OpenApi.DocGen

Renders an OpenAPI document (JSON or YAML) into a deterministic Markdown API reference: --input, --output (required), --title, --source-label, --path-prefix. Usage and I/O errors return non-zero.

WorkflowGenerator (withdrawn)

StellaOps.Tools.WorkflowGenerator was withdrawn on 2026-09-27 and frozen under src/__Obsoleted/Tools/. It had no consumer, and every workflow it generated ran a stella scan <target> --output sarif=... step that does not parse against the CLI command tree. stella ci init is the only CI workflow generator (GitHub Actions, GitLab CI and Gitea Actions; see the CLI command surface).

StellaOps.Bench (performance harnesses)

Collected from the former src/Bench/. .NET console harnesses (LinkNotMerge, LinkNotMerge.Vex, Notify, PolicyEngine, Scanner.Analyzers) and Python harnesses (ImpactIndex, PolicyCache, PolicyDelta, Signals, Determinism, Graph with a Node UI driver). They read frozen inputs and write benchmark results; they are not packaged as tools or shipped.

Bench (stella-vs-trivy compute and orchestration)

Developer-only C# projects for the stella-vs-trivy benchmark. StellaOps.Bench.Compute provides canonical JSON, structural JSON equivalence, golden fixture loading, DiscoveryTruth, DiscoveryHarcaseProbe, EvidenceScorer, CompareMetrics, ReportBuilder and CapsuleBuilder. StellaOps.Bench.Compute.Orchestration wraps the Docker and Git CLIs through System.Diagnostics.Process and hosts ProjectPreparerService and BenchRunOrchestrator. The stella-bench-compute run verb (StellaOps.Bench.Compute.Cli) exposes the orchestrator.

The shell scripts under tools/benchmarks/stella-vs-trivy/scripts/ select the engine: BENCH_ENGINE=csharp delegates the whole pipeline to stella-bench-compute run; BENCH_COMPUTE=csharp keeps bash orchestration but routes the compute verbs to the C# executable; with neither set the bash/jq/python path runs. Parity is asserted by StellaOps.Bench.Compute.Tests (BenchRunOrchestratorTests). These projects are not added to release solutions or packaging artifacts.

StellaOps.Verifier (standalone bundle verifier)

Absorbed from the former src/Verifier/. Assembly stella-verifier; verifies evidence bundles offline (--bundle, --trusted-keys, --trust-profile, --output, --format, --verify-signatures, --verify-timestamps). RuntimeIdentifiers win-x64, linux-x64, linux-musl-x64, osx-x64, osx-arm64; a single-file publish is self-contained.

StellaOps.Tools.TlptScoper (DORA TLPT scope generator)

Generates canonical tlpt-scope.v1 JSON. Local mode reads an Asset Registry v1 file (--asset-registry); live mode queries Graph’s Asset Registry (--graph-asset-registry-url, --graph-bearer-token) through the client contract in src/Graph/StellaOps.Graph.Api. Both modes apply the same filtering, mapping and hashing. See TLPT Scoper.

StellaOps.Sdk.Generator (SDK code generation)

Absorbed from the former src/Sdk/. Per-language generation scripts and config.yaml for Go, Java, Python and TypeScript, post-processing templates, and a pinned toolchain lock (toolchain.lock.yaml: openapi-generator-cli, JDK, Node).

StellaOps.DevPortal.Site (developer portal)

Absorbed from the former src/DevPortal/. An Astro/Starlight static site with a RapiDoc “Try It” console, and scripts for offline builds, link checks, accessibility and performance checks (scripts/build-offline.mjs, check-links.mjs, run-a11y.mjs, check-perf.mjs, sync-spec.mjs).

Supply-chain hardening suite

Deterministic, offline lanes under src/__Tests/supply-chain/ (01-jcs-property, 02-schema-fuzz, 03-rekor-neg, 04-big-dsse-referrers, 05-corpus) driven by run.sh, run.ps1 and run_suite.py. See supply-chain-hardening-suite.md.

Retired tools

FixtureUpdater and DebianTrackerImport were frozen on 2026-09-11 (SPRINT_20260722_003 VULN-B1, CoC 15.4) and moved to src/__Obsoleted/Tools/. Both operated only on the retired Concelier connector and persistence graph; the Vulnerabilities hub owns connector ingestion. They must not be compiled, referenced or run.

Data flow

1. GoldenPairs mirrors, diffs and validates the golden-pairs corpus.
2. The Policy tools read policy definitions and fixtures and write validation results, schema files or smoke verdicts in-process.
3. LanguageAnalyzerSmoke runs analyzers in-process over fixtures and compares golden snapshots.
4. NotifySmokeCheck reads the event stream and the Notify deliveries API and reports pass/fail.
5. RustFsMigrator reads an S3-compatible bucket and writes RustFS objects.
6. OpenApi.DocGen reads an OpenAPI document and writes Markdown.
7. Bench harnesses read frozen inputs and write reports; the stella-vs-trivy layer also drives Docker and Git subprocesses.
8. Verifier reads evidence bundles and writes a verification report.
9. TlptScoper reads Asset Registry input (file or Graph) and ReachGraph references and writes TLPT scope JSON.
10. Sdk.Generator and DevPortal.Site read the OpenAPI specification and produce SDK sources and a static site.

Database schema

None. No tool defines migrations or owns a schema. (The retired DebianTrackerImport wrote into the Concelier store; it is frozen.)

Endpoints

None. The tools are clients; none listens for connections.

Dependencies

Security considerations

• No listeners. No tool exposes an HTTP endpoint.
• Network use. NotifySmokeCheck (Valkey/Redis and Notify API), RustFsMigrator (S3-compatible storage and RustFS), TlptScoper live mode (Graph), and the Bench orchestration (Docker, Git) reach external infrastructure. The Policy tools, LanguageAnalyzerSmoke, OpenApi.DocGen and Verifier work on local files.
• Credentials. Connection details and tokens are supplied at run time through environment variables or options, not embedded in binaries or fixtures.
• Determinism. GoldenPairs, the Policy tools, LanguageAnalyzerSmoke, OpenApi.DocGen and TlptScoper use fixed times, stable ordering and byte-stable serialization.
• Bench isolation. Tool containers launched by the orchestration default to --network none; host paths are passed as argument-list entries.

Evidence