@jhlagado/azm 0.2.12 → 0.2.14

package/dist/src/register-contracts/summary.js

@@ -91,7 +91,7 @@ function applyStackPop(tokens, consumedProduced, intendedProduced, stack, state,
         }
         return;
     }
-    if (popped.length !== units.length) {
+    if (popped.tokens.length !== units.length) {
         for (const unit of units) {
             tokens.set(unit, { origin: 'unknown' });
             consumedProduced.delete(unit);
@@ -100,11 +100,35 @@ function applyStackPop(tokens, consumedProduced, intendedProduced, stack, state,
         return;
     }
     units.forEach((unit, idx) => {
-        tokens.set(unit, popped[idx] ?? { origin: 'unknown' });
+        tokens.set(unit, popped.tokens[idx] ?? { origin: 'unknown' });
         consumedProduced.delete(unit);
         intendedProduced.delete(unit);
     });
 }
+function stackFrameUnits(frameUnit) {
+    if (frameUnit === 'AF')
+        return ['A', 'sign', 'zero', 'halfCarry', 'parity', 'carry'];
+    if (frameUnit === 'BC')
+        return ['B', 'C'];
+    if (frameUnit === 'DE')
+        return ['D', 'E'];
+    if (frameUnit === 'HL')
+        return ['H', 'L'];
+    if (frameUnit === 'IX')
+        return ['IXH', 'IXL'];
+    return ['IYH', 'IYL'];
+}
+function consumeKnownBoundaryStackFrame(stack, state, knownBoundary) {
+    for (const frameUnit of knownBoundary?.consumesStackFrame ?? []) {
+        const expected = stackFrameUnits(frameUnit);
+        const popped = stack.pop();
+        if (popped === undefined ||
+            popped.units.length !== expected.length ||
+            !popped.units.every((unit, index) => unit === expected[index])) {
+            state.stackBalanced = false;
+        }
+    }
+}
 function applyUnknownStackUnits(tokens, consumedProduced, intendedProduced, units) {
     for (const unit of units) {
         tokens.set(unit, { origin: 'unknown' });
@@ -114,7 +138,10 @@ function applyUnknownStackUnits(tokens, consumedProduced, intendedProduced, unit
 }
 function applyStackEffect(tokens, consumedProduced, intendedProduced, stack, state, effect, expectedTerminalReturn, knownBoundary) {
     if (effect.stack.kind === 'push') {
-        stack.push(effect.stack.units.map((unit) => readToken(tokens, unit)));
+        stack.push({
+            units: effect.stack.units,
+            tokens: effect.stack.units.map((unit) => readToken(tokens, unit)),
+        });
         return;
     }
     if (effect.stack.kind === 'pop') {
@@ -126,6 +153,7 @@ function applyStackEffect(tokens, consumedProduced, intendedProduced, stack, sta
         applyUnknownStackUnits(tokens, consumedProduced, intendedProduced, effect.stack.units);
         return;
     }
+    consumeKnownBoundaryStackFrame(stack, state, knownBoundary);
     if (expectedTerminalReturn && stack.length !== 0) {
         state.stackBalanced = false;
     }

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

@@ -1,6 +1,6 @@
 import type { Diagnostic } from '../model/diagnostic.js';
 import type { LoadedProgram } from '../tooling/api.js';
-import type { AnalyzeRegisterContractsOptions, RegisterContractsOutputCandidate, RegisterContractsUnit } from './types.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsFinding, RegisterContractsOutputCandidate, RegisterContractsUnit } from './types.js';
 export interface RegisterContractsTextEdit {
     file: string;
     line: number;
@@ -42,6 +42,7 @@ export interface AnalyzeRegisterContractsForToolsOptions extends Omit<AnalyzeReg
 export type AnalyzeRegisterCareForToolsOptions = AnalyzeRegisterContractsForToolsOptions;
 export interface AnalyzeRegisterContractsForToolsResult {
     diagnostics: Diagnostic[];
+    findings: RegisterContractsFinding[];
     outputCandidates: RegisterContractsOutputCandidate[];
     candidateDiagnostics: RegisterContractsCandidateDiagnostic[];
     codeActions: RegisterContractsCodeAction[];

package/dist/src/register-contracts/tooling.js

@@ -46,12 +46,14 @@ export function analyzeRegisterContractsForTools(loaded, options) {
         ? baseResultOptions
         : { ...baseResultOptions, registerContractsProfile: profile });
     const outputCandidates = result.outputCandidates ?? [];
+    const findings = result.findings ?? [];
     const candidateDiagnostics = outputCandidates.map(diagnosticForOutputCandidate);
     const codeActions = outputCandidates
         .filter((candidate) => candidate.autoFixable === true)
         .map(codeActionForOutputCandidate);
     return {
         diagnostics: result.diagnostics,
+        findings,
         outputCandidates,
         candidateDiagnostics,
         codeActions,

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

@@ -1,8 +1,17 @@
 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';
+export type RegisterContractsStackFrameUnit = 'AF' | 'BC' | 'DE' | 'HL' | 'IX' | 'IY';
 /** @deprecated Use RegisterContractsUnit. */
 export type RegisterCareUnit = RegisterContractsUnit;
 export type SmartComment = {
@@ -28,6 +37,10 @@ export type SmartComment = {
     kind: 'expectOut';
     carriers: RegisterContractsUnit[];
     name?: string;
+} | {
+    kind: 'rcIgnoreNext';
+    findingKind: RegisterContractsFindingKind;
+    reason: string;
 };
 export interface LocatedSmartComment {
     file: string;
@@ -47,6 +60,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 +76,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 +97,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;
@@ -140,12 +162,17 @@ export interface RoutineSummary {
     valueRelations: ValueRelation[];
     stackBalanced: boolean;
     hasUnknownStackEffect?: boolean;
+    consumesStackFrame?: RegisterContractsStackFrameUnit[];
     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 +181,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,45 @@ 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.
 
+Some monitor ABIs deliberately consume a caller-prepared stack frame at a known
+boundary. The built-in MON3/TecMate profile models `RST $10` with `C=$53`
+(`MON_BANK_CALL`) as a service-specific boundary that consumes the top stack
+entries `AF`, `DE` and `HL`, returns `A` and carry from the banked target, and
+leaves the caller stack balanced. This is not a blanket relaxation for `RST`;
+the behavior is selected by the proven `C` service value. The same profile also
+provides a `C >= $60` TecMate expansion-service range fallback that returns
+`A` and carry for installed expansion services.
+
+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 +268,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 +284,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 +302,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.     |
@@ -112,6 +133,19 @@ Important options include:
 | `registerContractsInterfaces`                | External `.asmi` contract files.        |
 | `skipAssembly`                               | Run loading and analysis only.          |
 
+`registerContractsPolicy` matches the physical source file recorded on each
+register-contract routine, direct call and finding. In a single assembled
+translation unit, included files remain distinct physical files for diagnostics
+and policy matching. For example, if `monitor.asm` includes `rtc.asm` and
+`disassembler.asm`, a finding owned by `rtc.asm` is matched against `rtc.asm`,
+not only against the root `monitor.asm` path.
+
+This is independent of source ownership units: `.include` keeps the surrounding
+source ownership unit for import/visibility semantics, but policy matching uses
+the physical `sourceName`/finding file. This allows projects to audit retained
+legacy source one included file at a time while keeping the whole program in one
+assembled unit.
+
 `compile()` returns:
 
 ```ts
@@ -125,6 +159,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 +177,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 +230,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 +293,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