@jhlagado/azm 0.2.13 → 0.2.14

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

@@ -6,6 +6,11 @@ export interface RegisterContractsProfileSummary {
     rstDispatchers: Map<number, {
         selector: RegisterContractsUnit;
         services: Map<number, RoutineSummary>;
+        rangeServices?: {
+            min: number;
+            max?: number;
+            summary: RoutineSummary;
+        }[];
     }>;
 }
 export declare function rstTargetName(vector: number): string;

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

@@ -89,10 +89,14 @@ function mon3ApiServices(overrides) {
         'WRITE_SECTOR',
         'RGB_SCAN',
     ];
-    return new Map(names.map((serviceName, api) => [
+    const services = new Map(names.map((serviceName, api) => [
         api,
         overrides.get(api) ?? conservativeMon3ApiSummary(api, serviceName),
     ]));
+    for (const [api, summary] of overrides) {
+        services.set(api, summary);
+    }
+    return services;
 }
 export function rstDispatcherServiceTargetNames(vector, selectorValue) {
     const mon3 = getRegisterContractsProfile('mon3');
@@ -103,7 +107,10 @@ export function rstDispatcherServiceTargetNames(vector, selectorValue) {
     if (value === undefined)
         return [];
     const service = dispatcher.services.get(value);
-    return service ? [service.name] : [];
+    if (service)
+        return [service.name];
+    const rangeService = dispatcher.rangeServices?.find((entry) => value >= entry.min && (entry.max === undefined || value <= entry.max));
+    return rangeService ? [rangeService.summary.name] : [];
 }
 export function getRegisterContractsProfile(name) {
     if (name !== 'mon3')
@@ -168,6 +175,27 @@ export function getRegisterContractsProfile(name) {
         stackBalanced: true,
         hasUnknownStackEffect: false,
     };
+    const bankCall = {
+        name: mon3ApiTargetName(0x53, 'BANK_CALL'),
+        mayRead: ['B', 'C', 'H', 'L'],
+        mayWrite: ['A', 'B', 'C', 'D', 'E', 'H', 'L', ...FLAG_UNITS],
+        mayOutput: ['A', 'carry'],
+        preserved: [],
+        valueRelations: [{ out: ['A', 'carry'], from: [] }],
+        stackBalanced: true,
+        hasUnknownStackEffect: false,
+        consumesStackFrame: ['AF', 'DE', 'HL'],
+    };
+    const tecmateExpansionService = {
+        name: 'TECMATE_EXPANSION_SERVICE',
+        mayRead: ['C'],
+        mayWrite: ['A', ...FLAG_UNITS],
+        mayOutput: ['A', 'carry'],
+        preserved: ['B', 'C', 'D', 'E', 'H', 'L'],
+        valueRelations: [{ out: ['A', 'carry'], from: [] }],
+        stackBalanced: true,
+        hasUnknownStackEffect: false,
+    };
     return {
         name: 'mon3',
         rst: new Map([
@@ -212,7 +240,9 @@ export function getRegisterContractsProfile(name) {
                         [16, scanKeys],
                         [18, matrixScan],
                         [54, parseMatrixScan],
+                        [0x53, bankCall],
                     ])),
+                    rangeServices: [{ min: 0x60, summary: tecmateExpansionService }],
                 },
             ],
         ]),

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

@@ -29,6 +29,7 @@ export function buildProfileSummaries(profileName) {
         ...profile.rstServices.values(),
         ...[...profile.rstDispatchers.values()].flatMap((dispatcher) => [
             ...dispatcher.services.values(),
+            ...(dispatcher.rangeServices?.map((rangeService) => rangeService.summary) ?? []),
         ]),
     ];
 }
@@ -47,6 +48,9 @@ export function buildProfileSummaryLookup(profileName) {
         for (const summary of dispatcher.services.values()) {
             out.set(summary.name, summary);
         }
+        for (const rangeService of dispatcher.rangeServices ?? []) {
+            out.set(rangeService.summary.name, rangeService.summary);
+        }
     }
     return out;
 }

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

@@ -1,7 +1,7 @@
 import { getZ80InstructionEffect } from '../z80/effects.js';
 import { precedingCServiceName, precedingRegisterImmediateValue } from './boundaryHints.js';
 import { instructionHead } from './instruction-head.js';
-import { rstServiceTargetName, rstTargetName } from './profiles.js';
+import { rstDispatcherServiceTargetNames, rstServiceTargetName, rstTargetName } from './profiles.js';
 export function boundarySummary(routine, index, summaries) {
     const item = routine.instructions[index];
     if (!item)
@@ -38,6 +38,9 @@ function rstServiceBoundarySummary(routine, index, vector, summaries) {
     const previous = routine.instructions[index - 1];
     const numericService = precedingRegisterImmediateValue(previous, 'C');
     if (numericService !== undefined) {
+        const profileTarget = firstSummary(rstDispatcherServiceTargetNames(vector, (register) => register === 'C' ? numericService : undefined), summaries);
+        if (profileTarget !== undefined)
+            return profileTarget;
         const numericSummary = summaries.get(rstServiceTargetName(vector, String(numericService)));
         if (numericSummary !== undefined)
             return numericSummary;
@@ -45,3 +48,11 @@ function rstServiceBoundarySummary(routine, index, vector, summaries) {
     const service = precedingCServiceName(previous);
     return service ? summaries.get(rstServiceTargetName(vector, service)) : undefined;
 }
+function firstSummary(names, summaries) {
+    for (const name of names) {
+        const summary = summaries.get(name);
+        if (summary !== undefined)
+            return summary;
+    }
+    return undefined;
+}

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/types.d.ts

@@ -11,6 +11,7 @@ export interface RegisterContractsPolicy {
 /** @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 = {
@@ -161,6 +162,7 @@ export interface RoutineSummary {
     valueRelations: ValueRelation[];
     stackBalanced: boolean;
     hasUnknownStackEffect?: boolean;
+    consumesStackFrame?: RegisterContractsStackFrameUnit[];
     outputCandidates?: RegisterContractsUnit[];
 }
 export interface RegisterContractsOutputCandidate {

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

@@ -220,6 +220,15 @@ 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:
 

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

@@ -133,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

package/package.json

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