crux-shared

Shared infrastructure for the EDACrux suite: the cross-product Dart packages that WaveCrux, NetCrux, LintCrux and SimCrux all build on.

This is a Melos workspace. Nothing in it is specific to one product's domain — the rule is that a package earns its place here by being consumed by more than one product, not by sounding generic.

Visibility & license

License: Apache License 2.0, already in the tree — LICENSE, NOTICES, and an SPDX header on every source file. CI checks the headers (tool/spdx-headers.py) and the third-party attributions (tool/gen-notices.py) on every run.

Visibility: private during the public beta, like every product repo in the suite; public at the post-beta open-core flip, in lockstep with the four open-core product repos. Each open-core product consumes crux_shared from its pubspec.yaml, so once those repos go public this one has to as well, or the dependency chain breaks. Apache 2.0, with its explicit patent grant, also gives third-party tools a clean path to build CXP-compatible products against crux_cxp.

Everything here is intended to be public at the flip — there is no private subset. What must stay secret is kept out of this repository entirely:

• The licence-key signing private key. Keygen generates and holds it; it is in no repository and no CI secret store. What crux_license compiles in — the Keygen account id and the Ed25519 verify key — is public by design, and open_core_purity_test.dart fails if any code a product build can reach gains the ability to sign. The one signer in the tree, the crux-policy sign subcommand's, signs an organization's own policy file with the organization's own key and ships in no product; the guard exempts it by name and holds it to still being a signer.
• Keygen admin tokens and every other service credential.
• Pro and Enterprise feature implementations, which live in each product's private Pro overlay — or, when more than one overlay shares one, in a private Pro-tier shared repository that depends on this one and never the reverse (ADR 0005).

The telemetry ingest URLs and the concrete LiveTelemetryService do live here, in crux_telemetry: the whole collection pipeline is public so it can be read and stripped, and abuse is handled by the ingest Worker's validation, not by hiding the URL.

Packages

Every package has its own README with the full surface and the canonical wiring pattern, and its own CHANGELOG — a static guard in crux_workspace fails when either is missing. The table is a directory, not a specification.

Foundations (pure Dart, no Flutter dependency):

Package	Purpose
crux_async	Async/timing primitives, starting with Debouncer — coalesces a burst of calls into one trailing invocation, with run / cancel / flush / dispose. Lifted from LintCrux's own debouncer after an audit found the cancel/dispose-discipline bugs a shared implementation is meant to make hard to repeat.
crux_collections	Pure-Dart collection primitives, starting with LruCache — a bounded, insertion-ordered map that promotes on read and evicts least-recently-used, with an optional weight bound read at eviction time, an onEvict hook for values that own a resource, and an isPinned predicate for values still in use. Lifted from four copies that agreed on the shape and differed on whether a cached null counts as a hit.
crux_guards	Static-guard scanners the products run from their own test/static/ tests: the outline colour token never colours text, every localisation key is read or retained with a reason, a widget's ref is never used after an await without a mounted check, every modal opener runs inside ModalGuard.run (or is a showCruxDialog given a modalGuardKey), a dialog holding typed input is not scrim-dismissible, no private class duplicates CruxPanelEmptyState, no product ends its own process with dart:io's exit instead of cruxExit, and the Crux Desktop guard (cruxAuditCruxDesktop): no raw showDialog, AlertDialog, SimpleDialog, SnackBar, showSnackBar, Icons.more_vert, Switch or list-tile toggle outside a // crux-desktop: phone-only, <why> call site or a per-repo allow-list with exact counts that shrinks to empty. Syntax-based and pure Dart; every exemption list is exact.

Application infrastructure (Flutter):

Package	Purpose
crux_license	Tier vocabulary (LicenseTier, Open Core / EDU / Pro / Enterprise, with EDU feature-equivalent to Pro), FeatureGate, licenseTierProvider, the kBetaPeriod / kBetaExpiry beta-gating and build-shelf-life machinery, the kAiExperimental AI-assistant gate, and the FeatureTierBadge / EditionBadge chips. CruxLicenseValidator verifies Keygen-signed licence keys and licence files here, in the open: a key grants a tier and names the products it covers — one product, or all four on a Suite SKU. A second, Flutter-free entry point crux_license_core.dart carries the headless subset for dart build cli binaries.
crux_signing	Ed25519 signature verification, and nothing else — the one Ed25519 implementation in the suite. Hand-written from RFC 8032 §5.1.7 and checked against the RFC's own vectors including the malleability and small-order cases, specifically so that no cipher enters crux-shared: package:cryptography ships AES-GCM and ChaCha20, and pulling it in would put a cipher in every product and make the store builds' ITSAppUsesNonExemptEncryption=false untrue. No signing, no key generation, no key agreement. Three consumers verify through it: crux_license (licence keys and files), crux_policy (the organization's signed .crux-policy.json) and plugin governance. Pure Dart permanently — the crux-policy CLI and both products' headless CLIs need it.
crux_audit	The shared AuditEvent envelope, the AuditSink seam, and an append-only JSONL sink. The envelope is shared; the event kinds are not — a kind is a plain string the product registers, because a shared enum would need editing here every time any of four products learned a new event. The sink opens, appends one line and closes per event, which is what makes every rotation scheme work with no detection logic: this package does not rotate, because the organization already does. Write failures rather than throwing or failing silently — a product that crashed because it could not audit is worse than one that was never audited, and a log that quietly stopped is worse than both. No syslog transport, no webhook, no SIEM connector. carries the three kinds that describe the shared machinery itself (, , ) rather than a product's own business. Pure Dart permanently.

Layout

crux-shared/
├── analysis_options.yaml      # very_good_analysis at workspace root
├── pubspec.yaml               # Workspace-root pubspec (workspace members + melos config)
├── packages/                  # One directory per package — see the tables above
├── api/                       # Committed public-API goldens, one per package (see api/README.md)
├── tool/                      # Repo checks: api-snapshot.sh, check-consumers.sh, check-cxp-version.sh,
│                              #   coverage.sh, spdx-headers.py, gen-notices.py, supply-chain.py,
│                              #   no-bundled-engines.py; the unused-exports.py report; plus
│                              #   country-names.sh (a data map, not a check)
├── docs/adr/                  # Architecture decision records for cross-suite conventions
├── .github/workflows/ci.yml   # Analyze + test + API goldens, supply chain (licences, SBOM,
│                              #   advisories), per-package coverage floors
├── .github/workflows/consumers.yml
│                              # Analyze all four products against every commit here
└── .github/workflows/release-crux-policy.yml
                               # The one artifact in this repo a customer runs: builds, signs,
                               #   notarizes and publishes the `crux-policy` administrator CLI

Repo docs

• docs/adr/ — architecture decision records for conventions that span the suite (filename shapes, persistence formats, protocol choices). docs/adr/README.md is the index.
• api/README.md — what the public-API goldens are and how to regenerate them.
• CLAUDE.md — the contributor-facing charter: scope rules, versioning contract, deprecation policy, coding conventions.

Local development

# Install Melos once
dart pub global activate melos

# From the repo root
melos bootstrap        # pub get for every package
melos run analyze      # dart analyze --fatal-infos --fatal-warnings everywhere
melos run test         # tests for every package (dart test or flutter test as appropriate)
melos run format-check # verify formatting

# Outside Melos
tool/api-snapshot.sh --check   # are the public-API goldens current? (CI runs this)
tool/api-snapshot.sh --write   # regenerate after an intentional API change
tool/check-consumers.sh        # analyze all four products against this working tree
python3 tool/unused-exports.py # which exported symbols no consumer checkout references (a report)

CI runs on every push to main, every pull request, nightly, and on manual dispatch. Beyond the workspace's own format/analyze/test, it checks SPDX headers and third-party attributions, runs the browser-only tests of crux_policy, crux_cxp, crux_io and crux_telemetry in Chrome, verifies the API goldens, and enforces crux_cxp's semver discipline; a consumers job checks out each of the four products and analyzes it against the commit under test — the job that actually catches a breaking change — a supply-chain job gates licences and advisories and writes an SBOM, and a coverage job holds every package to its own floor.

Relationship to the suite

The suite's repositories, and which way the dependencies point:

crux-shared/   (this repo — private during beta, public Apache 2.0 post-beta)
wavecrux/      (open core — private during beta, public Apache 2.0 post-beta)
netcrux/       (same)
lintcrux/      (same)
simcrux/       (same)

Each open-core product repo holds crux-shared as a Git submodule of itself (e.g. wavecrux/crux-shared/), so each open core is buildable standalone — its consumers don't need to know about the suite structure. Each product's closed Pro overlay consumes its open core as a submodule and inherits crux-shared transitively through it.

Because there is no version solver between this repo and its consumers — every dependency is a bare path: into the submodule — the submodule SHA is the compatibility contract, and package version: fields are informational. crux_cxp is the exception: it goes to pub.dev at the flip and carries real semver discipline today. See CLAUDE.md § "Versioning contract" and § "Deprecation policy".

License

crux-shared is licensed under the Apache License 2.0 — see LICENSE for the full text and NOTICES for third-party attributions. Contributions require a signed Contributor License Agreement (CLA.md) — see CONTRIBUTING.md.

Apache-2.0 §6 grants no trademark rights, so the names and logos are covered separately — see TRADEMARK.md.