The JSON contract

Multiple directories are loaded and merged — a pack id repeated across directories is taken whole from the later directory. A missing/unreadable directory is a non-fatal warnings entry, not a failure.

The self-contained-binary alternative to packsDir for hosts with no pack directory on disk (e.g. zzop-mcp's compile-time-embedded packs). Loaded before packsDir directories, so a directory pack with the same id wins the collision whole. Additive (v0.16.0); the retired JS wrapper never sent it. Also accepted on analyzeEnvelope's config with the identical contract.

When non-empty, a pack whose id is absent does not run. The opt-in twin of disabledRules, which can only say "everything except". Empty means no allowlist (every loaded pack runs), never allow-nothing. Scoped to packs: native analyses keep running and stay disabledRules' business. Composes with disabledRules (the allowlist selects, disabledRules still subtracts).

Each { rule, path?, glob? } drops findings for rule — everywhere (no filter), in files whose path contains path (substring), or in files matching glob (full-path glob; glob wins over path).

Same path/glob matching as suppressions, but drops matching paths from every rule at once and from every other reporting channel — recommendations, crossLayerFindings, critical, and every per-metric violation list under scores.*.

It also removes the file from SCORING, as of 0.27: an excluded file stops being a judged subject, leaving both the violation list and the denominator behind every per-file score, so health.pain moves with it. The graph itself is untouched — the file is still analyzed, still in the dep graph, and still a real import target, so no other file's coupling, fan-out or blast radius changes. Note the direction is not predictable: excluding code that is cleaner than average raises pain, because the figure describes the population this config judges rather than the whole tree, and is only comparable against runs using the same exclude. A run whose exclude removed at least one file says so in warnings.

Two channels take no filter at all: warnings itself (which reports an exclude so broad the problem only looks absent — filtering it would let the filter erase its own warning), and rows keyed by a slice or module rather than a file (cohesion.slices, sdp.violations, mainSequence.modules, modularity), whose subject is a directory rather than a file.

Keyed by content hash + parser/ruleset fingerprint. Omit to run uncached — that is the answer on this wire, where no default is ever injected. A zzop/zzop-mcp/zzop.config.jsonc run is the other dialect: its config front end defaults the key to .zzop/cache and creates that directory on the first run — see A config is required.

Shape: { since?: string, recentDays?: number, commitTypePatterns?: { pattern, tag }[], commitSubjectPatterns?: { pattern, label }[] }. Enables git-derived scores/health/recommendations/critical/seams.

recentDays defaults to 30; commitTypePatterns, when non-empty, replaces the default FIX/FEAT/REVERT/... classifier table entirely.

commitSubjectPatterns is the declared subject-label axis and differs from its sibling in three deliberate ways: it has no default table (absent or empty labels nothing at all — what a "revert"/"ticket"/"hotfix" subject looks like is a per-project convention the engine will not guess), it is not first-match-wins (every matching declaration contributes its label, in declaration order, a repeated label kept once at its first position), and the pattern is compiled exactly as written — no implicit (?i) — against the raw subject.

Two warnings self-reports: a pattern that fails to compile (skipped, matches nothing), and a declared table that matched zero collected commits. Today those warnings are this key's only observable effect — the preserved subject and its labels stay on the engine-internal per-commit record and are not yet carried on any output channel. Known limit: git output is decoded with from_utf8_lossy, so a legacy-encoded subject (a commit object with no encoding header) is matched with each non-UTF-8 byte already replaced by U+FFFD — a pattern spelling those original characters cannot match it, and the zero-match warning says so when a U+FFFD is observed.

An object of optional convention-vocabulary keys — the authoritative list is zzop contract config-surface, and the engine type is zzop_engine::VocabularyConfig.

A name a framework fixed (@GetMapping, router.post) stays built in because nobody can rename it; a name the project chooses — what it calls its auth guards, which URL segments mark its API, where its Java sources live, which directories hold build output — is declarable here, because holding it as a built-in literal means the engine guesses and silently misclassifies every project that names it differently.

Per key, whole replacement: a key you name replaces its built-in list or pattern outright, never an element-wise merge (the same one-origin rule packs.extraDirs and git.commitTypePatterns state); a key you leave out is not judged, and a declared-but-empty value (null, "", []) means the same — there is no built-in fallback (removed 2026-07-27; the built-in values survive only as the defaults zzop init writes into your starter config, so they reach a run because your config says them). Leaving a key out makes rules fire more, not less: an undeclared exemption grants no exemption and an undeclared guard vocabulary proves no guard.

That is also why "declare nothing" is deliberately not spellable as "treat everything as a guard" — an empty guard pattern would be a regex matching every name (disable a judgment with rules: { "<id>": "off" } instead). A declared pattern that will not compile matches nothing rather than failing the run — it never falls back to a built-in, because substituting our pattern for the author's is exactly the guessing this vocabulary removes. skipDirs lands on the walker's own skip list so one list has one owner.

This is deliberately not the same roof as git.commitTypePatterns/git.commitSubjectPatterns: those configure the git collector and match commit messages, while every key here names something the analyzed code itself spells. zzop init writes every key with its built-in value, so the starter file documents these assumptions instead of hiding them.

The ESLint TIMING=1 / oxlint rule-timing equivalent. true times each DSL rule and each whole-graph native analysis that runs; false leaves ruleTimings null at zero added cost. Never changes findings/ir, and deliberately takes no part in the cache key — a profiled and an unprofiled run of the same tree are the same analysis and reuse each other's cache entries.

The one request field here with no zzop.config.jsonc key: a config declares what is true about the project and gets committed, while a timing report is a question about one invocation on one machine. CLI dialect: --profile-rules on analyze/analyze-envelope/cross. EnvelopeAnalyzeRequest carries the same field with the identical contract. Note a file served whole from cache never re-runs its per-file rules and contributes no timing, so a warm run reports only the whole-graph native analyses — the emitted report discloses this and carries the cache counts that prove it.

Shorthand for a mounts entry with dir: "", folded in last so an explicit equal-length mounts entry wins a tie. Stacks on top of any code-extracted prefix (e.g. NestJS's setGlobalPrefix).

Shape: { dir: string, at: string }[]. Deployment-topology per-directory mounts: prepends at to an http provide's key when its file path falls under dir.

The path prefix this tree's own outbound http calls carry, for when the base is assigned from a cross-file constant (axios.defaults.baseURL = settings.baseApiUrl) and the never-guess extractor therefore reads nothing. Prepended to every keyed relative kind=http consume of the tree, unscoped by client — a declaration speaks for the whole tree, as mountedAt does on the serving side. An unresolved consume and an absolute-URL key are never touched.

Unlike mountedAt, stacking is warned, not silent: if a readable literal base was already applied from the code, the declaration still wins but warnings names both prefixes, because on the calling side a second prefix is usually a duplicate rather than a second real layer. A declaration that rewrites nothing warns too.

An absolute-URL consume from another tree targeting one of these hosts is re-keyed to an internal joinable key at cross-layer link time instead of counting as external egress.

Shape: { key: string, role?: "provide" | "consume" }[]. Lightweight route-fact injection for the common case: a non-literal path, a dynamic verb, a computed URL.

key is a "METHOD PATH" interface key (e.g. "GET /api/users"), normalized through the same transform the extractors use for that side; role picks whether the route is served here (provide, default) or called from here (consume). The whole array expands into one synthetic adapter overlay of http provides/consumes, composing through the same cross-layer join path as a hand-authored overlay. A malformed key is soft-skipped with a warning, never a hard error.

Partial Normalized-AST envelopes (typically just io + fragment channels for a handful of files) — how a framework/SDK adapter adds IoFacts the engine does not parse natively, without reimplementing the parser. Each overlay is re-validated and soft-skipped with a warning if invalid. Contrast analyzeEnvelope, where a full envelope replaces native analysis. See NORMALIZED_AST.md.

Shape: { globOverrides?: { glob: string, language: string }[] }. Applied in order (first match wins) ahead of the extension map, for the files whose extension lies about what they contain: a .txt holding SQL, a vendored .inc that is really PHP-free Java.

An entry naming a language this build does not have is skipped with a warning rather than failing the run — an unknown language is a config-authoring mistake, and the run's other trees still have honest answers to give. A separate roof from vocabulary on purpose: every key under that one names something the project calls its own, while this one names a path→parser mapping.

Vocab-free counts of which channels this tree filled (files, parserDispatched, symbols, resolvedImportEdges, declaredImportsByExt — the per-extension declared-specifier denominator for that edge count, counted before resolution; an absent extension key means never measured, not 0 — ioProvides, ioConsumesKeyed, ioConsumesUnresolved, degraded) plus the active-blindness fact joinContributionZero. Every cell is defined in the coverage census below.

Not gated by git — always present, even for an empty tree. Each row counts nodeCount, not fileCount: a node exists only for a dep-graph key or a git-touched path, so summing these rows does not reproduce the top-level fileCount (files walked), and with git off a lexical-only file is in no row at all.

A finding suppressed by an inline marker comment never appears at all. The shape every finding shares — and what its severity does and does not assert — is defined below the index.

Every score ships the population it scored over — featureSlicedDesign.layerClassifiedImports, cohesion.sliceCount, coupling.importerCount, godFile.total, busFactor.total, diamond.rootsExamined, mainSequence.classifiedFiles and their siblings. A population of 0 is the never measured signal, not a clean bill of health: every formula returns 100 on an empty population, so the denominator is the only thing separating "judged everything and all passed" from "found nothing it could judge".

Each is a judged-population denominator, never a tree total: the top-level exclude removes a path from both the violation list and the denominator, and fileSizeCompliance/godFile judge source files only. mainSequence.classifiedFiles is 0 on every current build (nothing classifies a file abstract vs concrete), so read only its instability/fileCount. What each key means rides beside it in scoreMeanings.

Present exactly when scores is, absent (not null) otherwise. One score key is a bare acronym and the legend is where it is expanded: sdp (Stable Dependencies Principle). Two more used to be and were renamed on the wire instead: sfc → fileSizeCompliance, fsd → featureSlicedDesign. A fourth, lod (Law of Demeter), was removed along with its score in 2026-08 — it had never measured anything. Each sentence says what a low number means; all scores are 0–100, higher is healthier.

Shape: {pain, axisPain[], measuredWeight, totalWeight, contributors[]}. pain carries no rule findings — a tree full of SQL injection scores exactly what the same tree scores with none — and most of what it does carry is a structural opinion rather than a defect claim.

axisPain[] says so on the wire: it splits pain into defect (import cycles, the only one), opinion (barrel discipline, FSD layering, SDP/Main Sequence, Newman modularity, LOC ceilings — a project that deliberately does the opposite is not wrong, it scores low) and history (rename churn, bus factor), each on pain’s own scale and summing to it.

pain renormalizes over the metrics that had a population, so an axis this tree could not measure leaves the weighting entirely instead of quietly scoring 100 and making the repo look healthier. Read pain against measuredWeight / totalWeight, which says how much of the metric table was measurable here; pain is null (never 0) when none of it was. contributors[] keeps the unmeasured metrics as rows with population: 0 and a null gap, so a dark axis is stated rather than absent.

An item whose file carries a rule-confirmed critical finding moves (never copies) into a synthetic urgent-bug-risk group; its roi number never changes.

blastRadius * ln(loc + 2), blast radius as tie-break — because a 5-line re-export barrel and a 400-line core of equal blast are not equal danger. blastRadius itself is the transitive dependent count; re-sorting this array by it alone gives a different order.

files counts that folder's dep-graph keys, not files walked, and noise folders (tests, dist, docs, …) are skipped whole. temporalBoundary is filtered twice over — only commits touching 2–25 files, and only each file's top 10 co-change partners — so it is the strongest measured cross-folder co-change, not a total.

null unless git is set; [] (not null) when git is active but no pair meets the co-change threshold. coChanges is a subset total: commits touching fewer than 2 or more than 25 files are skipped as noise, so read it as "N filtered co-changes", never "these layers changed together N times".

The same evidence the dep-graph descriptions draw on. null = git inactive or collection failed, so nothing was measured; [] = measured and nothing co-changed — the two must not be folded together. Carries the same two noise filters as layerCoChurn, so it is a sample rather than a total. Not gated by disabledRules: it is measured evidence, not a rule verdict. Paths are relative to the analyzed tree, like nodes and dep: history is collected per repository and then rebased onto each tree root, so a package inside a monorepo sees its own co-change and never its sibling's.

Shape: { recentDays, since } | null. null is the "git didn't run" signal (same gating as scores). recentDays is the resolved number (the caller's value, or the 30 default); since is the caller's raw filter string, or null for full history.

Shape: { id, rules, ruleIds, source, filesInScope, zeroAdmissionRules? }[], sorted by id, with each pack's rule count and provenance (source: "dir" = read from a packsDir directory, "inline" = packDefs). ruleIds is the LIST behind the rules COUNT — every rule id this run could have reported from that pack, so "does this run carry a rule named X" is answered from the reply instead of guessed from the pack prefix. Always present: an omitted list would read as "this build declines to say", which is exactly the state a validator has to tell apart from "no such rule".

filesInScope counts the files a pack's rules are path-eligible to scan (file_pattern candidacy, before any content check) — pair filesInScope > 0 with zero findings to read "ran, found nothing" versus filesInScope: 0 "nothing in scope." zeroAdmissionRules is the same census per rule: the ids of this pack's rules whose own path gates (file_pattern plus that rule's file_exclude_pattern) admit zero files here — their zero findings are scope, not "checked and clean". Present only when non-empty; omitted on a filesInScope: 0 pack, whose pack-level zero already covers every rule.

Always present — [] is the honest "zero DSL packs loaded" state. Verifies a custom pack actually loaded without inferring it from findings deltas.

One sentence per key: row (an entry is one loaded pack — loading is not running), filesInScope (path candidacy, never a "matched" count, and the presence of the key is itself the claim that the pack ran), and zeroAdmissionRules (those rules admitted no analyzed file at all — not "files reached them and nothing fired"). Those two readings imply opposite things; it has always meant the first, and now says so. A fourth key, didNotRun, appears only when a pack really was gated off — a legend entry for a state this run is not in is noise, and noise is what teaches readers to skip disclosures. It sits beside the array rather than inside it because packsLoaded is an array: inside, the same sentences would repeat once per loaded pack (same shape as scoreMeanings).

Shape: { registered, disabled, reportedInCrossLayerFindings }. registered is how many native analyses this build carries — the denominator the two lists are read against. It counts the gate id space (what rules/disabledRules name), not the ids a finding can carry: some gate score computations that emit no finding, and some are umbrella ids whose findings carry finer schema/<label> names.

The two lists are kept apart because the remedies are opposite. disabled = your config switched these off, so their absence from findings means not analyzed; turn one back on to get a verdict. reportedInCrossLayerFindings = these are switched on and still cannot appear here, because they judge the cross-tree join and report into its own crossLayerFindings channel, which a per-tree output does not have; run the cross-layer join over the same config to see them. Anything registered and in neither list ran — except for the kinds the paragraph above named. A score-gating id emits no finding at all, and an umbrella id's findings arrive under the finer schema/<label> names, so neither can key findings under the name registered counted: a blank there is how those ids always look, not a verdict (for an umbrella, look under schema/<label> instead). For everything else in neither list, absence from findings is a measured zero.

Both lists are always serialized, [] included — unlike zeroAdmissionRules, deliberately. A list that appears only when it has entries reports nothing on a clean run in bytes indistinguishable from a build that does not report at all, which is the confusion this object exists to end.

One sentence per key: registered, disabled, reportedInCrossLayerFindings, plus everythingElse — the residual class that has no field of its own precisely because it is the case where absence is the verdict. Unconditional, unlike packsLoadedMeaning: a run can legitimately load no pack, but every build registers native analyses.

Shape: { disabled, severityRemapped, only } — that disabledRules/severityOverrides/packsOnly were applied, listing the affected rule ids, with only being the honored pack allowlist (packs.only), outside which a pack never ran. Omitted (or empty) when none of the three was requested — treat an absent key as "no overrides," never null.

Computed at analysis time: a disabledRules/severityOverrides entry matching no known rule id is reported here (only analysis time has the full known-id set). [] means neither knob had a matching-nothing entry.

Set profileRules: true on the request to populate it (CLI dialect: zzop analyze --profile-rules / zzop analyze-envelope --profile-rules / zzop cross --profile-rules); null when profiling was off, which is the default. It has no zzop.config.jsonc key — a timing report is a question about one invocation on one machine, not a fact about the project — and no MCP tool argument turns it on, so an analyze_repo reply carries no timings today.

EnvelopeAnalyzeRequest carries the same field: Mode A's pack evaluation (symbol-scan per file, io-scan whole-tree) and its whole-graph analyses feed the same timing accumulator the native path uses. Profiling never changes findings/ir and takes no part in the cache key; a file served whole from cache re-runs no per-file rule and contributes no timing, so a WARM run reports only the whole-graph native analyses.

zzop's honest list of which classes of blindness it does and does not yet detect. On a multi-tree analyzeTrees call it sits once beside trees, never per tree. Its three fields are defined in the registry legend below.

This index is the FACADE wire, which carries the full array — it is the derivation source. The shaped product replies (zzop analyze/cross/endpoint and their MCP twins) carry a fold instead since 2026-07-29: the counts plus a pointer (zzop contract disclosure-classes / zzop://contract/disclosure-classes). The prose is run-invariant, so it ships once rather than on every call.