Diagnostics — codes, suppression, summary

jinflow make reports problems as numbered diagnostics — E001, W042, N003 — drawn from a central registry. Each code is stable across versions, greppable, suppressible by code, and promotable to error. The end-of-run summary rolls them up so a one-line glance tells you what’s wrong.

This is the same shape gcc, clang, rustc, eslint, and every other compiler-style tool has used for decades. If you’ve ever passed -Wno-unused-variable or -Werror to a compiler, you already know it.

The shape of a diagnostic

  [W003 WARNING] Previous build did not finish — starting fresh. — no stamp on existing KLS

• W003 — the code (registry key, never reused)
• WARNING — the severity (NOTE / WARNING / ERROR)
• Previous build did not finish — starting fresh. — the registry description
• no stamp on existing KLS — the per-instance text (callsite-specific detail)

Severity classes

Class	Codes	Effect
Note	N###	Informational. Never affects exit code.
Warning	W###	Recoverable. Exit code 0 unless promoted via --deny=W### or -Werror.
Error	E###	Build cannot proceed. Exit code 1.

Code numbering is loosely zoned:

• E000-E099 — fatal errors (build cannot proceed)
• E100+ — recoverable errors (build continues, count shown)
• W000-W099 — generic warnings (state, config, fallbacks)
• W100+ — domain warnings (per pack / per pipeline)
• N000+ — notes
• 000 in any class is the untyped fallback for legacy callsites that haven’t migrated yet

Filtering: --allow, --deny, -Werror

# Silence W003 for this run
jinflow make hrcentral.vai --allow=W003

# Comma-separated also works
jinflow make hrcentral.vai --allow=W003,W008,W042

# Promote a single warning to an error
jinflow make hrcentral.vai --deny=W006

# Promote ALL warnings to errors (CI-friendly)
jinflow make hrcentral.vai -W           # short form
jinflow make hrcentral.vai --werror     # long form

Behavior:

• --allow=W### — silenced records still register in the JSON output (so accounting stays honest), but they don’t print and don’t count toward the warning total.
• --deny=W### — promotes the named warning to an error. Counts as an error in the summary; the build’s exit code becomes 1.
• -Werror / --werror — promotes every warning to an error. Useful in CI where any warning should fail the build.
• An --allow always wins over --deny/-Werror for the same code (silenced first, never even considered for promotion).

The flags accept arbitrary code strings. Typos in --allow=W099X are silently accepted — the same forgiveness gcc shows for -Wno-foo when foo doesn’t exist. We don’t want a typo to brick a build.

Per-tenant defaults: diagnostics: block in jinflow.yml

For warnings that are persistently acceptable in a particular tenant (or environment), declare them in the tenant’s jinflow.yml:

afs/jinflow.yml

tenant: rmc
pack: numetrix
diagnostics:
  allow: [W003, W008]   # silence these codes for every rmc build
  deny:  [W006]         # promote these to errors
  werror: false         # set true to make all warnings errors

Tenant-block settings are additive to CLI flags:

• Tenant allow + CLI --allow are unioned.
• Tenant deny + CLI --deny are unioned.
• Tenant werror: true forces -Werror even if the CLI didn’t ask. The CLI cannot turn off a tenant’s werror (use --allow for the specific codes you want to permit).

The block is optional and best-effort: a missing block, missing file, or malformed YAML is silently skipped — diagnostics never break a build.

Inline pragma in YAML files

When a single signal/thesis/verdict YAML legitimately produces a known warning, add a pragma at the top of that file:

# jinflow: allow=W042
# This perspective intentionally aggregates across signals — the
# weight-mismatch warning is expected.

signal_id: perspective_material_health
type: assessment
...

The pragma is read by the YAML loader and applied only while validating that file. Other files in the same build see the warning normally.

Multiple directives are supported:

# jinflow: allow=W003,W008
# jinflow: deny=W014

…or combined:

# jinflow: allow=W003 deny=W014

werror is not supported at file scope (rarely useful, surprising to readers). Use the tenant block for blanket promotion.

End-of-run summary

After every jinflow make, the summary block prints:

  ⚠ 4 errors, 27 warnings, 3 suppressed
    W003×15, W007×8, W042×4, E001×2, E042×2

    [W003 WARNING] Previous build did not finish — starting fresh. (×15)
        no stamp on existing KLS
        commit 25748b12 missing
        ... and 13 more
    [W007 WARNING] Stash pop had conflicts ... (×8)
        ...
    [E001 ERROR] DLZ is required ... (×2)
        ...

Three sections:

1. Headline — total counts by severity, plus suppressed.
2. Per-code breakdown — code×count in descending order.
3. Sample texts — first 3 per-instance messages per code, then ... and N more.

Suppressed codes appear as [W003 WARNING suppressed] in the breakdown without sample texts (you asked for silence; we honor it).

Promoted warnings appear as [W003→ERROR] so it’s clear why a W### is counting as an error.

Machine-readable output: --json

For CI scripts:

jinflow make hrcentral.vai --json

Emits a JSON document:

{
  "summary": {
    "errors": 4,
    "warnings": 27,
    "notes": 0,
    "suppressed": 3,
    "exit_code": 1,
    "by_code": {"E001": 2, "W003": 15, "W042": 4}
  },
  "records": [
    {
      "code": "W003",
      "severity": "warning",
      "effective_severity": "warning",
      "description": "Previous build did not finish — starting fresh.",
      "text": "no stamp on existing KLS",
      "suppressed": false,
      "context": {}
    }
  ]
}

effective_severity reflects --deny / -Werror promotions; severity is the registry-declared one. Suppressed records have suppressed: true and effective_severity: null.

Persistent record: _{tenant}.diagnostics in the KLS

At the end of every jinflow make, the diagnostic record buffer is baked into a per-tenant table inside the KLS:

SELECT code, severity, effective_severity, description, text, suppressed, recorded_at
FROM "_rmc".diagnostics
ORDER BY recorded_at DESC, code;

Schema:

Column	Type	Notes
code	VARCHAR	E001 / W042 / N003
severity	VARCHAR	registry-declared severity
effective_severity	VARCHAR	after --deny / -Werror (NULL if suppressed)
description	VARCHAR	registry description
text	VARCHAR	per-instance message
suppressed	BOOLEAN	silenced via --allow
context_json	VARCHAR	extra context fields (JSON or NULL)
recorded_at	VARCHAR	ISO 8601 UTC of the bake

The table is dropped and rewritten on every build — it always reflects the most recent run. Mirrors the _{tenant}.snapshot / _{tenant}.afs_archive pattern that makes the KLS self-describing.

JinDesk reads this table to surface “27 warnings from last build, 3 errors” on the build-history page (where applicable).

Authoring new codes

Codes live in jinflow/cli/commands/diagnostics.py:

W_NO_DLZ = Diag(
    "W001", Severity.WARNING,
    "No DLZ configured — DLZ-dependent phases will be skipped.",
)

Three rules:

1. Codes are stable. Once a code is in the registry, it’s never renumbered or removed. Deprecated codes get a deprecated: note in the description but stay reserved.
2. Severity matches prefix. E### codes must be Severity.ERROR; W### must be Severity.WARNING; N### must be Severity.NOTE. The Diag.__post_init__ check enforces this.
3. Description should be self-contained. It prints with every emission, even when the caller provides no per-instance text.

To emit:

from jinflow.cli.commands.diagnostics import W_NO_DLZ, warn

warn(W_NO_DLZ)                      # bare emission — registry text only
warn(W_NO_DLZ, "configure jinflow.yml first")  # with per-instance detail

The registry validates that the function (warn / error / note) matches the diagnostic’s severity — warn(E_DLZ_REQUIRED) raises a ValueError. This catches misuse at callsite, not at runtime under load.

Related

• Make (Build) — the build pipeline that emits diagnostics
• Operating Modes — how make runs across deployment topologies