@jhlagado/azm 0.2.12 → 0.2.13

package/dist/src/register-contracts/types.d.ts

@@ -1,5 +1,13 @@
 import type { Z80Instruction } from '../z80/instruction.js';
 export type RegisterContractsMode = 'off' | 'audit' | 'warn' | 'error' | 'strict';
+export type RegisterContractsReportFormat = 'text' | 'json';
+export type RegisterContractsInferenceFormat = 'json' | 'markdown';
+export type RegisterContractsPolicyMode = 'off' | 'audit' | 'strict';
+export interface RegisterContractsPolicy {
+    strict?: readonly string[];
+    audit?: readonly string[];
+    off?: readonly string[];
+}
 /** @deprecated Use RegisterContractsMode. */
 export type RegisterCareMode = RegisterContractsMode;
 export type RegisterContractsUnit = 'A' | 'B' | 'C' | 'D' | 'E' | 'H' | 'L' | 'IXH' | 'IXL' | 'IYH' | 'IYL' | 'SPH' | 'SPL' | 'carry' | 'zero' | 'sign' | 'parity' | 'halfCarry';
@@ -28,6 +36,10 @@ export type SmartComment = {
     kind: 'expectOut';
     carriers: RegisterContractsUnit[];
     name?: string;
+} | {
+    kind: 'rcIgnoreNext';
+    findingKind: RegisterContractsFindingKind;
+    reason: string;
 };
 export interface LocatedSmartComment {
     file: string;
@@ -47,6 +59,9 @@ export interface RegisterContractsInstruction {
     file: string;
     line: number;
     column: number;
+    sourceUnit?: string;
+    sourceRelation?: 'entry' | 'include' | 'import';
+    sourceUnitRelation?: 'entry' | 'include' | 'import';
     labels: string[];
     constants?: ReadonlyMap<string, number>;
 }
@@ -60,6 +75,9 @@ export interface RegisterContractsRoutine {
     constants?: ReadonlyMap<string, number>;
     span: {
         file: string;
+        sourceUnit?: string;
+        sourceRelation?: 'entry' | 'include' | 'import';
+        sourceUnitRelation?: 'entry' | 'include' | 'import';
         start: {
             line: number;
             column: number;
@@ -78,6 +96,9 @@ export interface RegisterContractsDirectCall {
     file: string;
     line: number;
     column: number;
+    sourceUnit?: string;
+    sourceRelation?: 'entry' | 'include' | 'import';
+    sourceUnitRelation?: 'entry' | 'include' | 'import';
 }
 /** @deprecated Use RegisterContractsDirectCall. */
 export type RegisterCareDirectCall = RegisterContractsDirectCall;
@@ -143,9 +164,13 @@ export interface RoutineSummary {
     outputCandidates?: RegisterContractsUnit[];
 }
 export interface RegisterContractsOutputCandidate {
+    kind?: 'output_candidate';
     file: string;
     line: number;
     column: number;
+    sourceUnit?: string;
+    sourceRelation?: 'entry' | 'include' | 'import';
+    sourceUnitRelation?: 'entry' | 'include' | 'import';
     routine: string;
     carriers: RegisterContractsUnit[];
     autoFixable?: boolean;
@@ -154,35 +179,167 @@ export interface RegisterContractsOutputCandidate {
 /** @deprecated Use RegisterContractsOutputCandidate. */
 export type RegisterCareOutputCandidate = RegisterContractsOutputCandidate;
 export interface RegisterContractsConflict {
+    kind?: 'definite_contract_violation' | 'flag_lifetime_risk';
     file: string;
     line: number;
     column: number;
+    sourceUnit?: string;
+    sourceRelation?: 'entry' | 'include' | 'import';
+    sourceUnitRelation?: 'entry' | 'include' | 'import';
+    routine?: string;
     callTarget: string;
     carriers: RegisterContractsUnit[];
     message: string;
 }
 /** @deprecated Use RegisterContractsConflict. */
 export type RegisterCareConflict = RegisterContractsConflict;
+export type RegisterContractsFindingKind = 'definite_contract_violation' | 'flag_lifetime_risk' | 'missing_callee_contract' | 'unknown_control_flow' | 'external_interface_unknown' | 'output_candidate';
+interface RegisterContractsFindingBase {
+    kind: RegisterContractsFindingKind;
+    file: string;
+    line: number;
+    column: number;
+    sourceUnit?: string;
+    sourceRelation?: 'entry' | 'include' | 'import';
+    sourceUnitRelation?: 'entry' | 'include' | 'import';
+    message: string;
+    routine?: string;
+    carriers?: RegisterContractsUnit[];
+}
+export interface RegisterContractsConflictFinding extends RegisterContractsFindingBase {
+    kind: 'definite_contract_violation' | 'flag_lifetime_risk';
+    callTarget: string;
+}
+export interface RegisterContractsUnknownBoundaryFinding extends RegisterContractsFindingBase {
+    kind: 'missing_callee_contract' | 'external_interface_unknown';
+    callTarget: string;
+    subject: string;
+}
+export interface RegisterContractsStackFinding extends RegisterContractsFindingBase {
+    kind: 'unknown_control_flow';
+    routine: string;
+    stackBalanced: boolean;
+    hasUnknownStackEffect?: boolean;
+}
+export interface RegisterContractsOutputCandidateFinding extends RegisterContractsFindingBase {
+    kind: 'output_candidate';
+    routine: string;
+    autoFixable?: boolean;
+}
+export type RegisterContractsFinding = RegisterContractsConflictFinding | RegisterContractsUnknownBoundaryFinding | RegisterContractsStackFinding | RegisterContractsOutputCandidateFinding;
 export interface RegisterContractsReportModel {
     entryFile: string;
     mode: RegisterContractsMode;
     profile?: string;
     summaries: RoutineSummary[];
+    findings?: RegisterContractsFinding[];
+    suppressedFindings?: RegisterContractsSuppressedFinding[];
     conflicts: RegisterContractsConflict[];
     outputCandidates?: RegisterContractsOutputCandidate[];
     unknownCalls: string[];
+    ratchet?: RegisterContractsRatchetResult;
+}
+export interface RegisterContractsJsonLocation {
+    file: string;
+    line: number;
+    column: number;
+    sourceUnit?: string;
+    sourceRelation?: 'entry' | 'include' | 'import';
+    sourceUnitRelation?: 'entry' | 'include' | 'import';
+}
+export interface RegisterContractsJsonRemediation {
+    category: 'add_contract' | 'fix_call_or_contract' | 'review_control_flow' | 'review_output_contract';
+    hint: string;
+}
+export interface RegisterContractsJsonFinding {
+    kind: RegisterContractsFindingKind;
+    location: RegisterContractsJsonLocation;
+    message: string;
+    routine?: string;
+    callTarget?: string;
+    subject?: string;
+    carriers?: RegisterContractsUnit[];
+    stackBalanced?: boolean;
+    hasUnknownStackEffect?: boolean;
+    autoFixable?: boolean;
+    remediation: RegisterContractsJsonRemediation;
+}
+export interface RegisterContractsSuppression {
+    file: string;
+    line: number;
+    column: number;
+    findingKind: RegisterContractsFindingKind;
+    reason: string;
+}
+export interface RegisterContractsSuppressedFinding {
+    finding: RegisterContractsFinding;
+    suppression: RegisterContractsSuppression;
+}
+export interface RegisterContractsJsonReportModel {
+    format: 'azm-register-contracts-report';
+    version: 1;
+    entryFile: string;
+    mode: RegisterContractsMode;
+    profile?: string;
+    summaries: RoutineSummary[];
+    findings: RegisterContractsJsonFinding[];
+    suppressedFindings?: Array<{
+        finding: RegisterContractsJsonFinding;
+        suppression: RegisterContractsSuppression;
+    }>;
+    unknownCalls: string[];
+    ratchet?: RegisterContractsRatchetResult;
+}
+export interface RegisterContractsInferenceRoutine {
+    name: string;
+    in: RegisterContractsUnit[];
+    out: RegisterContractsUnit[];
+    clobbers: RegisterContractsUnit[];
+    preserves: RegisterContractsUnit[];
+    confidence: 'explicit' | 'inferred' | 'draft';
+    callerImpact: {
+        outputCandidateCount: number;
+        outputCandidateCarriers: RegisterContractsUnit[];
+    };
+}
+export interface RegisterContractsInferenceModel {
+    format: 'azm-register-contracts-inference';
+    version: 1;
+    routines: RegisterContractsInferenceRoutine[];
+}
+export interface RegisterContractsRatchetEntry {
+    identity: string;
+    finding: RegisterContractsJsonFinding;
+}
+export interface RegisterContractsRatchetResult {
+    baselineFile?: string;
+    newFindings: RegisterContractsRatchetEntry[];
+    removedFindings: RegisterContractsRatchetEntry[];
+    changedFindings: Array<{
+        identity: string;
+        baseline: RegisterContractsJsonFinding;
+        current: RegisterContractsJsonFinding;
+    }>;
 }
 export interface AnalyzeRegisterContractsOptions {
     mode: RegisterContractsMode;
+    policy?: RegisterContractsPolicy;
     emitReport: boolean;
+    reportFormat?: RegisterContractsReportFormat;
     emitInterface: boolean;
+    emitInference?: boolean;
+    inferenceFormat?: RegisterContractsInferenceFormat;
     emitAnnotations?: boolean;
     fixRegisterContracts?: boolean;
     registerContractsProfile?: 'mon3';
     interfaceContracts?: RoutineContract[];
     acceptedOutputCandidates?: ReadonlyMap<string, RegisterContractsUnit[]>;
+    baselineReport?: RegisterContractsJsonReportModel;
+    baselineFile?: string;
+    ratchet?: boolean;
 }
 export interface RegisterContractsAnnotationFile {
     readonly path: string;
     readonly text: string;
 }
+export {};

package/dist/src/syntax/parse-line.js

@@ -67,6 +67,9 @@ function commentOnlyLine(line) {
                     column: firstNonWhitespaceColumn(line.text),
                     ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
                     ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
+                    ...(line.sourceUnitRelation !== undefined
+                        ? { sourceUnitRelation: line.sourceUnitRelation }
+                        : {}),
                 },
             },
         ],

package/docs/codebase/02-source-loading-and-parsing.md

@@ -107,10 +107,13 @@ been identified.
 
 `src/source/logical-lines.ts` scans a `SourceFile` into `LogicalLine` objects. A
 logical line records the source name, line number and original text. Tooling
-loads can also attach `sourceUnit` and `sourceRelation`:
+loads can also attach `sourceUnit`, `sourceRelation` and `sourceUnitRelation`:
 
 - `sourceUnit` is the owning file for the current tooling unit
-- `sourceRelation` is `entry`, `include` or `import`
+- `sourceRelation` says how this physical file entered the current expansion
+  step: `entry`, `include` or `import`
+- `sourceUnitRelation` says how the owning source unit entered the load:
+  `entry` or `import`
 
 This thin structure gives every later diagnostic a stable location and enough
 provenance for tooling features that need to reason about module ownership.
@@ -176,10 +179,11 @@ line is a label, instruction, directive, layout declaration or comment item.
 - comments
 
 Each item carries a source span where appropriate. Tooling spans now preserve
-optional `sourceUnit` and `sourceRelation` fields when the loader attached them.
-Assembly uses item kind to decide size and emission. Register contract analysis
-uses instruction, label and comment items to build routines. D8 map output uses
-spans to connect emitted bytes back to files and lines.
+optional `sourceUnit`, `sourceRelation` and `sourceUnitRelation` fields when
+the loader attached them. Assembly uses item kind to decide size and emission.
+Register contract analysis uses instruction, label and comment items to build
+routines. D8 map output uses spans to connect emitted bytes back to files and
+lines.
 
 ## Top-Level Parse Order
 

package/docs/codebase/04-ops-and-register-contracts.md

@@ -168,7 +168,10 @@ without exposing them outside the module.
 `src/register-contracts/smartComments.ts` reads AZMDoc comments from the comment maps
 captured during loading. Comment-block splitting and token parsing live in
 `smartCommentBlocks.ts` and `smartCommentParsing.ts`. External `.asmi`
-contracts are parsed in `interfaceContracts.ts`.
+contracts are parsed in `interfaceContracts.ts`. The same parser also accepts
+inline suppression comments in the form
+`;! rc-ignore-next <finding-kind>: <reason>` for the next finding at that
+location.
 
 Contracts can describe:
 
@@ -184,6 +187,11 @@ routine contract. Source comments attach to routines in the current program.
 The compact source form can place several clauses on one `;!` line, for
 example `;! in A; out A; clobbers F`.
 
+`.asmi` parsing stays strict. Files may contain `extern` or `service rst`
+boundaries, `in`, `out`, `clobbers` and `preserves` clauses, then `end`.
+Comment lines are rejected so interface files stay machine-generated and
+deterministic.
+
 ## Effects, Summaries and Liveness
 
 Register contract analysis depends on `src/z80/effects.ts`. Effects describe which registers
@@ -212,10 +220,36 @@ summaries before the final pass. Strict mode uses `stackBalanced` and
 `hasUnknownStackEffect` to distinguish balanced stack use from a routine whose
 boundary may leave the stack in an unknown state.
 
+The analysis now emits typed findings rather than only free-form conflict text.
+The current finding set covers:
+
+- `definite_contract_violation`
+- `flag_lifetime_risk`
+- `missing_callee_contract`
+- `external_interface_unknown`
+- `unknown_control_flow`
+- `output_candidate`
+
+Policy and suppression handling operate on those finding kinds. Report JSON,
+tooling consumers and baseline ratchets all use the same typed finding model.
+
+`policy.ts` resolves per-file register-contract modes from `strict`, `audit`
+and `off` glob lists. Specific patterns win over broad patterns, then stricter
+matches win ties. This lets one compile run audit imported wrappers while
+keeping core files in strict mode or disabling analysis for known external
+shims. When policy disables a file, unresolved call targets in that file no
+longer surface as ordinary unknown-symbol diagnostics.
+
 ## Reports, Interfaces and Tooling
 
-`report.ts` renders human-readable `.regcontracts.txt` reports and `.asmi` interface
-metadata. It also renders generated source contracts as one compact `;!` line,
+`report.ts` renders human-readable `.regcontracts.txt` reports, JSON report
+payloads, `.asmi` interface metadata and review-oriented inference exports. The
+text and JSON reports share one model with routine summaries, findings,
+suppressed findings, unknown calls and optional ratchet results. Inference
+exports are lighter-weight routine summaries for review workflows and can be
+rendered as JSON or Markdown.
+
+`report.ts` also renders generated source contracts as one compact `;!` line,
 joining `in`, `out`, `maybe-out` and `clobbers` clauses with semicolons.
 When a routine may clobber the full flag set, the source form uses `F` as the
 compact carrier name. `annotate.ts`, `annotations.ts`, `fix.ts` and
@@ -225,7 +259,12 @@ conservative fixes.
 The CLI can request these behaviours through:
 
 - `--reg-report`
+- `--reg-report-format`
+- `--reg-baseline`
+- `--reg-ratchet`
 - `--reg-interface`
+- `--reg-infer`
+- `--reg-infer-format`
 - `--contracts`
 - `--fix`
 - `--accept-out`
@@ -236,6 +275,11 @@ file, line, column, message, fixability and optional text edits. An editor can
 show the same register contract information that the CLI reports while using
 normal editor actions for accepted fixes.
 
+`analyzeRegisterContractsForTools()` now also returns the structured findings
+list and output candidate list beside candidate diagnostics and code actions, so
+tooling integrations can render the same categorised analysis that the CLI
+writes to report artifacts.
+
 ## Changing Ops or Register Contracts
 
 Op changes belong in `src/expansion/`, with tests under
@@ -249,7 +293,8 @@ Register contract changes usually begin in one of these files:
   `instruction-operands.ts`, `instruction-predicates.ts`
 - Summary inference: `summary.ts`
 - Caller liveness: `liveness.ts`
-- Output text: `report.ts`
+- Policy selection and ratchets: `policy.ts`, `ratchet.ts`
+- Output text and structured exports: `report.ts`
 - Source edits: `annotate.ts`, `fix.ts`, `annotations.ts`
 - Tooling surface: `tooling.ts`
 

package/docs/codebase/05-interfaces-and-output-artifacts.md

@@ -68,6 +68,14 @@ when artifact writing succeeds.
 artifact suppression, include paths, source-root, case-style linting, directive
 aliases and register contract options.
 
+Register-contract parsing now includes:
+
+- report format selection with `--reg-report-format text|json`
+- baseline comparison with `--reg-baseline <report.json>`
+- ratcheting with `--reg-ratchet`
+- inference export with `--reg-infer`
+- inference format selection with `--reg-infer-format json|markdown`
+
 `src/cli/write-artifacts.ts` maps parsed options into
 `CompileNextFunctionOptions` and calculates the output stem.
 `src/cli/artifact-files.ts` writes in-memory artifacts to disk. If the user
@@ -76,6 +84,13 @@ path and side artifacts use the same base. If the user supplies only
 `program.asm`, AZM writes outputs next to the entry source using the source
 stem.
 
+Register-contract side artifacts now use suffixes derived from the selected
+format:
+
+- `.regcontracts.txt` or `.regcontracts.json` for reports
+- `.asmi` for inferred interfaces
+- `.regcontracts.inference.json` or `.regcontracts.inference.md` for review exports
+
 ## Compile API
 
 `src/api-compile.ts` exports:
@@ -103,8 +118,14 @@ Important options include:
 | `d8mInputs`                                  | Artifact paths recorded in D8 metadata. |
 | `emitBin`, `emitHex`, `emitD8m`, `emitAsm80` | Artifact selection.                     |
 | `registerContracts`                          | Register contract mode.                 |
-| `emitRegisterReport`                         | Emit `.regcontracts.txt` artifact.      |
+| `registerContractsPolicy`                    | Per-file strict, audit and off policy.  |
+| `emitRegisterReport`                         | Emit text or JSON report artifact.      |
+| `registerContractsReportFormat`              | Report format, `text` or `json`.        |
+| `registerContractsBaseline`                  | Baseline JSON report for ratcheting.    |
+| `registerContractsRatchet`                   | Fail when findings increase.            |
 | `emitRegisterInterface`                      | Emit `.asmi` artifact.                  |
+| `emitRegisterInference`                      | Emit inference review artifact.         |
+| `registerContractsInferenceFormat`           | Inference format, `json` or `markdown`. |
 | `emitRegisterAnnotations`                    | Emit source annotation artifact.        |
 | `fixRegisterContracts`                       | Apply conservative source fixes.        |
 | `acceptRegisterOutputCandidates`             | Promote selected output candidates.     |
@@ -125,6 +146,11 @@ Diagnostics describe every warning or error observed during loading, analysis,
 register contract analysis, assembly or artifact creation. Artifacts contain the
 in-memory outputs requested by options.
 
+When analysis is enabled, `compile()` can now suppress ordinary unresolved-call
+diagnostics for files whose register-contract policy resolves to `off`. That
+keeps policy-controlled external boundaries in the register-contract report path
+rather than duplicating them as symbol failures.
+
 The older option names `registerCare`, `registerCareProfile` and
 `registerCareInterfaces` remain as deprecated aliases for package consumers.
 New callers should use the `registerContracts...` names.
@@ -138,17 +164,29 @@ helpers.
 `loadProgramNext()` returns a loaded program with source items, source texts and
 source line comments. `analyzeProgramNext()` runs semantic checks and returns
 symbols. `analyzeRegisterContractsForTools()` returns register contract
-diagnostics and code actions in a form suitable for editors.
+diagnostics, typed findings, output candidates and code actions in a form
+suitable for editors.
 
 The tooling loader now recognises both `.include` and `.import`. Both directives
 flatten source into one parse stream. `.import` also marks parsed spans with a
 new source ownership unit, while `.include` keeps the surrounding owner's unit.
-Editor features can use `item.span.sourceUnit` and `item.span.sourceRelation`
-to distinguish module-owned declarations from text included into another unit.
+Editor features can use `item.span.sourceUnit`, `item.span.sourceRelation` and
+`item.span.sourceUnitRelation` together: `sourceRelation` tracks the physical
+file edge that produced the parsed item, while `sourceUnitRelation` tracks
+whether the owning unit entered as the entry source or through `.import`.
 Diagnostics, symbols and source segments continue to use physical source file
 paths, so imported files appear as their own files in editor and Debug80 map
 metadata.
 
+`analyzeProgramNext()` now also enforces the completed import-visibility pass.
+Visibility checks walk instruction operands, data expressions, equates,
+alignment and bin-range expressions and bare `.ds` size expressions. Imported
+private labels remain visible inside their own source unit, including op
+generated references and text included into that same unit. When a name already
+collides with an equate, enum member or case-insensitive type or enum
+declaration, assembly keeps the duplicate-symbol or duplicate-type diagnostic
+instead of replacing it with a visibility error.
+
 An editor integration usually starts with:
 
 ```ts
@@ -179,6 +217,7 @@ The output layer uses structured artifact objects from `src/outputs/types.ts`:
 - `Asm80Artifact`
 - `RegisterContractsReportArtifact`
 - `RegisterContractsInterfaceArtifact`
+- `RegisterContractsInferenceArtifact`
 - `RegisterContractsAnnotationsArtifact`
 
 Each artifact has a `kind` field. Callers can switch on `kind` to find the
@@ -241,11 +280,22 @@ supported.
 
 Register contract report, interface and annotation artifacts are created through
 `runRegisterContracts()` in `src/api-register-contracts.ts` and flow through
-the same compile result and CLI write path. The report is human-readable. The `.asmi`
-interface is metadata that can be loaded by later compile runs through
+the same compile result and CLI write path. Reports can be human-readable text
+or JSON. The `.asmi` interface is metadata that can be loaded by later compile runs through
 `--interface`. Annotation artifacts write source files when `--contracts` or
 `--fix` is used.
 
+The register-contract report artifact now carries optional structured payloads:
+`format`, `json` and the active `findings` list. JSON reports use the stable
+`azm-register-contracts-report` envelope with summaries, findings, suppressed
+findings, unknown calls and optional ratchet results.
+
+Inference artifacts carry a routine-oriented `azm-register-contracts-inference`
+model. Each routine records inferred `in`, `out`, `clobbers` and `preserves`
+carriers, an inference confidence and caller-impact counts for output
+candidates. Markdown rendering is intended for review, while JSON is suitable
+for automation and regression tooling.
+
 ## Public API Compatibility
 
 The public API is defined by package exports and exported TypeScript types.

package/docs/codebase/06-verification-and-maintenance.md

@@ -55,8 +55,9 @@ between modules rather than inside one helper.
 
 Source-loading and tooling provenance changes belong here as well. The
 `stage-11-tooling-api.test.ts` integration suite covers include and import
-resolution, recursive load failures and the span ownership metadata that tools
-read from parsed items.
+resolution, recursive load failures, span ownership metadata and import
+visibility analysis across direct calls, jump fixups, data expressions, bare
+`.ds` sizes, duplicate-symbol precedence and include-only wrappers.
 
 ## CLI, ASM80 and Differential Tests
 
@@ -65,6 +66,10 @@ failure modes, determinism, case-style linting and register contract switches.
 Users experience the command-line behaviour through argument parsing,
 diagnostics, output paths and exit status.
 
+The register-contract CLI suite now also covers JSON report output, inference
+artifact output, baseline loading and ratchet failures so option parsing and
+artifact suffix rules stay stable.
+
 CLI tests also protect deterministic output. `compareDiagnosticsForCli()` sorts
 diagnostics by file, line, column, severity, code and message. A CLI test can
 catch changes that leave the compiler correct but make terminal output unstable.
@@ -153,6 +158,8 @@ Ask what kind of fact the change affects:
 - Instruction-chain splitting belongs in `source/`, while inline source
   generation and op template expansion belong in `expansion/`.
 - Routine contracts and liveness belong in `register-contracts/`.
+- Register-contract policy matching, suppression parsing and ratchets also
+  belong in `register-contracts/`.
 - Artifact shape belongs in `outputs/`.
 - User commands belong in `cli/`.
 - Package consumers belong in `api-compile.ts`, `api-tooling.ts` and
@@ -187,6 +194,7 @@ This book should change when:
 - public package exports change
 - CLI option groups change
 - output artifact shapes change
+- register-contract finding kinds, policy rules or report schemas change
 - a major subsystem gains a new responsibility
 - tests or guardrails are reorganised
 

package/docs/codebase/appendices/a-directory-file-reference.md

@@ -139,11 +139,13 @@ you need to find the owner of a behaviour quickly.
 | `carriers.ts`                | Normalizes register contract carrier names and expands register pairs.                                  |
 | `controlFlow.ts`             | Successor logic for routine instruction flow.                                                           |
 | `profiles.ts`                | Built-in external routine profiles such as MON-3.                                                       |
-| `report.ts`                  | Renders `.regcontracts.txt`, `.asmi` and compact source contract blocks.                                |
+| `report.ts`                  | Renders text and JSON register-contract reports, inference exports, `.asmi` output and compact source contract blocks. |
 | `annotate.ts`                | Inserts or replaces generated contract blocks near routine labels.                                      |
 | `annotations.ts`             | Builds source annotation artifact data.                                                                 |
 | `fix.ts`                     | Finds and applies conservative expected-output fixes.                                                   |
 | `accept-output.ts`           | Parses user-accepted output candidate options.                                                          |
+| `policy.ts`                  | Resolves per-file strict, audit and off register-contract policy matches.                               |
+| `ratchet.ts`                 | Compares current JSON findings against a baseline report.                                               |
 | `tooling.ts`                 | Editor-friendly register contract diagnostics and code actions.                                         |
 | `types.ts`                   | Register contract unit, routine, effect, summary, contract and report types.                            |
 | `sourceText.ts`              | Source line splitting and joining helpers for text edits.                                               |

package/docs/codebase/appendices/b-compile-flow-reference.md

@@ -23,7 +23,7 @@ compile(entryFile, options, deps)
       expand textual .include and tooling .import
       collect source texts
       collect source line comments
-      attach source ownership metadata
+      attach source ownership metadata and unit ancestry
       scan logical lines
     read directive alias profiles
     build directive alias policy
@@ -43,7 +43,9 @@ compile(entryFile, options, deps)
     read AZMDoc and .asmi contracts
     infer summaries
     run liveness
-    build report, interface and annotation artifacts
+    apply suppressions and scoped policy
+    compare JSON findings against optional baseline
+    build report, interface, inference and annotation artifacts
   assembleProgram()
     buildAddressState()
     emitProgramImage()
@@ -85,7 +87,7 @@ analyzeProgramNext(loaded)
 
 analyzeRegisterContractsForTools(loaded)
   run register contract analysis in audit-oriented tooling mode
-  return candidate diagnostics and code actions
+  return findings, candidate diagnostics and code actions
 ```
 
 `analyzeRegisterCareForTools()` remains as a deprecated compatibility export for
@@ -97,8 +99,8 @@ tooling integrations that still use the older name.
 | ------------------ | -------------------- | ------------------------------------- |
 | Source loading     | entry path           | logical lines with ownership metadata, source texts, comments |
 | Parsing            | logical lines        | source items                          |
-| Analysis           | source items         | diagnostics, symbols                  |
-| Register contracts | loaded program       | summaries, conflicts, reports         |
+| Analysis           | source items         | diagnostics, symbols, import-visibility checks |
+| Register contracts | loaded program       | summaries, findings, reports and inference artifacts |
 | Assembly           | source items         | byte map, symbols, source segments with per-item columns |
 | Outputs            | byte map and symbols | artifacts                             |
 | CLI                | artifacts            | files on disk                         |

package/docs/codebase/appendices/c-public-surface-reference.md

@@ -44,6 +44,16 @@ want one import path.
 Use this path for build tools, Debug80 integration and scripts that need bytes
 or artifacts.
 
+Compile consumers should treat these register-contract options as public when
+they use that subsystem:
+
+- `registerContractsPolicy`
+- `registerContractsReportFormat`
+- `registerContractsBaseline`
+- `registerContractsRatchet`
+- `emitRegisterInference`
+- `registerContractsInferenceFormat`
+
 ## Tooling Exports
 
 `@jhlagado/azm/tooling` exposes:
@@ -62,9 +72,10 @@ Use this path for editors, linters and language tooling.
 `analyzeRegisterCareForTools` remains as a deprecated compatibility export.
 
 Tooling consumers should treat parsed item spans as provenance-bearing data.
-When present, `sourceUnit` names the owning source unit and `sourceRelation`
-records whether that unit entered the load through `entry`, `include` or
-`import`.
+When present, `sourceUnit` names the owning source unit, `sourceRelation`
+records whether the physical file edge was `entry`, `include` or `import`, and
+`sourceUnitRelation` records whether the owning unit entered the load through
+`entry` or `import`.
 
 ## CLI Export
 
@@ -95,12 +106,15 @@ Treat these as public contracts:
 - `D8mSymbol`
 - `LoadedProgramNext`
 - `AnalyzeProgramNextResult`
+- `RegisterContractsFinding`
+- `RegisterContractsFindingKind`
+- `RegisterContractsInferenceModel`
 - `RegisterContractsCandidateDiagnostic`
 - `RegisterContractsCodeAction`
 
 For tooling consumers, this contract also includes the optional
-`SourceSpan.sourceUnit` and `SourceSpan.sourceRelation` fields carried on parsed
-items.
+`SourceSpan.sourceUnit`, `SourceSpan.sourceRelation` and
+`SourceSpan.sourceUnitRelation` fields carried on parsed items.
 
 When these shapes change, update package tests, TypeScript type tests, README
 examples, repo-local reference docs and this manual.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhlagado/azm",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {