Module envelope 

JSON-output envelope and utility types: SchemaVersion, ToolVersion, ElapsedMs, AuditIntroduced, plus the shared Meta, BaselineDeltas, BaselineMatch, RegressionResult, EntryPoints, and CheckSummary shapes referenced by every per-command envelope. The structs are always compiled (the JSON emission layer constructs them at runtime); the schemars::JsonSchema derive is gated per-struct on the schema feature. Typed envelope and utility-shape structs for the JSON output contract.

Today the JSON serialization layer (crates/cli/src/report/json.rs) builds its envelopes (CheckOutput, HealthOutput, …) via serde_json::json! macros and ad-hoc map merging. The types in this module are the schema-side counterpart of those envelopes plus a small set of utility shapes (SchemaVersion, Meta, BaselineDeltas, …) that the envelopes reference.

Gated on the schema cargo feature so consumers that do not need the schemars::JsonSchema derive (every crate except fallow-cli with --features schema-emit) skip the schemars compile cost.

Structs

AuditIntroduced

Audit-mode marker emitted on each finding when fallow audit --format json runs with a base ref. true means the finding’s structural key was not present at the base ref (introduced by the current changeset); false means it was inherited. Duplication findings carry one carve-out: a clone group whose structural key is new but whose instances contain no added line from the diff (a group re-shaped by removing duplication elsewhere) is demoted to inherited and serializes false (issue #2164). Such demoted groups additionally carry a demotion_reason field naming the rule, and are counted in attribution.duplication_demoted (issue #2220).

BaselineCategoryDelta

Single-category baseline delta entry inside BaselineDeltas::per_category.

BaselineDeltas

Per-category delta comparison against a saved baseline. Only present in CheckOutput when --baseline is used.

BaselineMatch

Baseline match statistics. Shows how many baseline entries existed and how many matched current issues. Useful for detecting stale baselines programmatically. Only present in CheckOutput when --baseline is used.

CheckSummary

Per-category issue counts for dead-code analysis. Always present in CheckOutput; when --summary is used the individual issue arrays are omitted but this object stays populated.

ElapsedMs

Analysis duration in milliseconds. Renders to the JSON wire as a bare integer.

EntryPoints

Entry-point detection summary embedded in CheckOutput and the combined envelope.

Meta

Metric and rule definitions emitted under _meta when --explain is passed (always present in MCP responses). Helps AI agents and CI systems interpret metric values without re-reading the docs site.

MetaMetric

Single-metric definition inside Meta::metrics.

MetaRule

Single-rule definition inside Meta::rules.

RegressionResult

Result of regression detection (--fail-on-regression). Compares current issue counts against a baseline from config or an explicit file.

SchemaVersion

Schema version for this output format (independent of tool version). Bump policy: ADDITIVE changes (new optional top-level fields, new optional struct fields, new array entries, new MCP tools, new CLI flags that map to new optional fields) do NOT bump the version; consumers receive new fields without breaking. BREAKING changes (renamed fields, removed fields, type changes, enum-variant removals, semantic changes to existing fields) DO bump. Additions to existing enum-valued required fields bump the affected envelope version so strict JSON Schema consumers can migrate. ComplexityContributionKind is non-exhaustive so Rust consumers retain a wildcard. To detect newly-added fields without a bump, check field presence via JSON-key existence rather than gating on the version. v4 was introduced alongside fallow-cov-protocol 0.2 (per-finding verdict, stable IDs, evidence block, renamed summary fields); v5 introduced health_score formula_version 2 with scale-invariant scoring semantics; v6 widened AddToConfigAction.value from a scalar string to oneOf: [string, array] so the new ignoreExports action can carry a paste-ready array of { file, exports } rule objects (the legacy ignoreDependencies etc. variants still emit strings, so consumers that switch on config_key keep working unchanged). v8 added the required duplication spread field and changed duplicated_tokens to count redundant copies, excluding the retained copy in each group. Envelopes embedding health use their own version marker, so health-only contract changes do not advance dead-code or unrelated sibling envelopes. The runtime-coverage block is extended additively as the protocol evolves (currently 0.3, which adds an optional capture_quality summary field). Other additive examples: dupes –group-by adds optional grouped_by, total_issues, groups fields without bumping.

TelemetryMeta

Privacy-safe local run metadata emitted for JSON consumers.

ToolVersion

Fallow CLI version that produced this envelope. Renders to the JSON wire as a bare string (e.g. "2.74.0").

TypeAwareAbstentionCounts

Closed abstention reason counts for stable machine consumption.

TypeAwareMeta

Bounded provenance emitted when the opt-in type-aware pass runs.

TypeAwarePhaseTimings

Semantic sidecar timings, separated from Fallow’s syntactic pipeline.

TypeAwareProjectMeta

Bounded provenance for one TypeScript project handled by the sidecar.

Enums

RegressionStatus

Status of a regression-check pass.

RegressionToleranceKind

Interpretation of RegressionResult::tolerance.

TypeAwareAbstentionReason

Closed set of reasons for retaining a candidate without semantic scanning.

TypeAwareInvalidationKind

How a persistent semantic snapshot was refreshed.

TypeAwareProjectSource

How a TypeScript project was selected for semantic refinement.

TypeAwareProjectStatus

Outcome of semantic refinement for one TypeScript project.