@jhlagado/azm 0.2.12 → 0.2.14

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.14",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {