@jhlagado/azm 0.2.13 → 0.2.15

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

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { normalize } from 'node:path';
 import { analyzeRegisterContracts } from './register-contracts/analyze.js';
 import { parseAcceptedOutputCandidates } from './register-contracts/accept-output.js';
-import { parseInterfaceContracts } from './register-contracts/interfaceContracts.js';
+import { parseInterfaceContractsDetailed } from './register-contracts/interfaceContracts.js';
 export function shouldAnalyzeRegisterContracts(options) {
     const registerContractsMode = options.registerContracts ?? options.registerCare ?? 'off';
     return (registerContractsMode !== 'off' ||
@@ -19,7 +19,7 @@ export function shouldAnalyzeRegisterContracts(options) {
 export async function runRegisterContracts(loadedProgram, options) {
     const diagnostics = [];
     const artifacts = [];
-    const interfaceContracts = await loadInterfaceContracts(options.registerContractsInterfaces ?? options.registerCareInterfaces ?? [], diagnostics);
+    const parsedInterfaces = await loadInterfaceContracts(options.registerContractsInterfaces ?? options.registerCareInterfaces ?? [], diagnostics);
     if (hasErrors(diagnostics)) {
         return { diagnostics, artifacts };
     }
@@ -49,7 +49,12 @@ export async function runRegisterContracts(loadedProgram, options) {
                 registerContractsProfile: options.registerContractsProfile ?? options.registerCareProfile,
             }
             : {}),
-        ...(interfaceContracts.length > 0 ? { interfaceContracts } : {}),
+        ...(parsedInterfaces.contracts.length > 0
+            ? { interfaceContracts: parsedInterfaces.contracts }
+            : {}),
+        ...(parsedInterfaces.serviceRanges.length > 0
+            ? { interfaceServiceRanges: parsedInterfaces.serviceRanges }
+            : {}),
         ...(baselineReport !== undefined ? { baselineReport } : {}),
         ...(options.registerContractsBaseline !== undefined
             ? { baselineFile: normalize(options.registerContractsBaseline) }
@@ -121,6 +126,7 @@ async function loadBaselineReport(rawPath, diagnostics) {
 }
 async function loadInterfaceContracts(interfaces, diagnostics) {
     const interfaceContracts = [];
+    const serviceRanges = [];
     for (const rawInterface of interfaces) {
         const contractPath = normalize(rawInterface);
         if (contractPath.slice(-5).toLowerCase() !== '.asmi') {
@@ -133,11 +139,13 @@ async function loadInterfaceContracts(interfaces, diagnostics) {
             continue;
         }
         const interfaceText = await readFile(contractPath, 'utf8');
-        for (const contract of parseInterfaceContracts(interfaceText, contractPath).values()) {
+        const parsed = parseInterfaceContractsDetailed(interfaceText, contractPath);
+        for (const contract of parsed.contracts.values()) {
             interfaceContracts.push(contract);
         }
+        serviceRanges.push(...parsed.serviceRanges);
     }
-    return interfaceContracts;
+    return { contracts: interfaceContracts, serviceRanges };
 }
 function hasErrors(diagnostics) {
     return diagnostics.some((diagnostic) => diagnostic.severity === 'error');

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

@@ -21,7 +21,8 @@ export function analyzeRegisterContracts(loaded, options) {
         }
     }
     const profileSummaries = buildProfileSummaries(options.registerContractsProfile);
-    let summaries = buildSummaries(program.routines, contractMap, profileSummaries);
+    const interfaceServiceRanges = options.interfaceServiceRanges ?? [];
+    let summaries = buildSummaries(program.routines, contractMap, profileSummaries, interfaceServiceRanges);
     summaries = withAcceptedOutputs(summaries, options.acceptedOutputCandidates);
     let summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
     const knownRoutines = knownRoutineNames(program.routines, contractMap.keys(), options.registerContractsProfile);
@@ -53,7 +54,7 @@ export function analyzeRegisterContracts(loaded, options) {
         summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
     }
     const conflicts = shouldBuildOutputCandidates
-        ? program.routines.flatMap((routine) => findRegisterContractsConflicts(routine, summariesByName, smartComments))
+        ? program.routines.flatMap((routine) => findRegisterContractsConflicts(routine, summariesByName, smartComments, interfaceServiceRanges))
         : [];
     const { outputCandidates: outputCandidatesWithAutoFixability, outputCandidateFixability } = outputCandidatesWithFixability(program.routines, outputCandidatesForPromotion);
     const { outputCandidates: allOutputCandidatesWithAutoFixability } = outputCandidatesWithFixability(program.routines, outputCandidates);

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

@@ -4,8 +4,10 @@ function unique(items) {
 export function labelIndex(routine) {
     const out = new Map();
     routine.instructions.forEach((item, index) => {
-        for (const label of item.labels)
-            out.set(label, index);
+        for (const label of item.labels) {
+            if (!out.has(label))
+                out.set(label, index);
+        }
     });
     return out;
 }

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

@@ -1,2 +1,7 @@
-import type { RoutineContract } from './types.js';
+import type { RegisterContractsServiceRangeContract, RoutineContract } from './types.js';
+export interface ParsedInterfaceContracts {
+    contracts: Map<string, RoutineContract>;
+    serviceRanges: RegisterContractsServiceRangeContract[];
+}
 export declare function parseInterfaceContracts(text: string, file?: string): Map<string, RoutineContract>;
+export declare function parseInterfaceContractsDetailed(text: string, file?: string): ParsedInterfaceContracts;

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

@@ -9,8 +9,12 @@ const INTERFACE_CONTRACT_BUILDERS = {
     preserves: (carriers) => ({ kind: 'preserves', carriers }),
 };
 export function parseInterfaceContracts(text, file = '<register-contracts-interface>') {
+    return parseInterfaceContractsDetailed(text, file).contracts;
+}
+export function parseInterfaceContractsDetailed(text, file = '<register-contracts-interface>') {
     const comments = [];
     const serviceAliases = new Map();
+    const serviceRanges = new Map();
     const lines = text.split(/\r?\n/u);
     for (const [index, line] of lines.entries()) {
         const trimmed = line.trim();
@@ -28,6 +32,10 @@ export function parseInterfaceContracts(text, file = '<register-contracts-interf
             if (serviceAliasesForComment !== undefined) {
                 serviceAliases.set(comment.name, serviceAliasesForComment);
             }
+            const serviceRangeForComment = parseInterfaceServiceRange(trimmed);
+            if (serviceRangeForComment !== undefined) {
+                serviceRanges.set(comment.name, serviceRangeForComment.range);
+            }
         }
         comments.push({ file, line: index + 1, comment });
     }
@@ -45,7 +53,10 @@ export function parseInterfaceContracts(text, file = '<register-contracts-interf
         if (hasContractContent(contract))
             out.set(name, contract);
     }
-    return out;
+    return {
+        contracts: out,
+        serviceRanges: [...serviceRanges.values()].filter((range) => out.has(range.target)),
+    };
 }
 function parseInterfaceContractLine(line) {
     const trimmed = line.trim();
@@ -74,6 +85,9 @@ function parseInterfaceServiceAliases(trimmed) {
     return parseInterfaceService(trimmed)?.aliases;
 }
 function parseInterfaceService(trimmed) {
+    const range = parseInterfaceServiceRange(trimmed);
+    if (range !== undefined)
+        return { primary: range.primary, aliases: range.aliases };
     const match = /^service\s+rst\s+(\S+)\s+(\S+)\s+(\S+)(?:\s+(\S+))?\s*$/i.exec(trimmed);
     if (match === null)
         return undefined;
@@ -87,6 +101,35 @@ function parseInterfaceService(trimmed) {
     const aliases = name === undefined ? [] : [rstServiceTargetName(vector, name)];
     return { primary, aliases };
 }
+function parseInterfaceServiceRange(trimmed) {
+    const match = /^service\s+rst\s+(\S+)\s+(\S+)\s+>=\s*(\S+)(?:\s+(\S+))?\s*$/i.exec(trimmed);
+    if (match === null)
+        return undefined;
+    const vector = parseInterfaceNumber(match[1]);
+    const selector = match[2].toUpperCase();
+    const min = parseInterfaceNumber(match[3]);
+    if (vector === undefined || min === undefined || selector !== 'C')
+        return undefined;
+    const primary = rstServiceRangeTargetName(vector, min);
+    const explicitName = match[4];
+    const aliases = explicitName === undefined ? [] : [explicitName];
+    return {
+        primary,
+        aliases,
+        range: {
+            vector,
+            selector: 'C',
+            min,
+            target: explicitName ?? primary,
+        },
+    };
+}
+function rstServiceRangeTargetName(vector, min) {
+    return `${rstTargetPrefix(vector)}:C>=$${min.toString(16).toUpperCase().padStart(2, '0')}`;
+}
+function rstTargetPrefix(vector) {
+    return `RST_$${vector.toString(16).toUpperCase().padStart(2, '0')}`;
+}
 function parseInterfaceNumber(raw) {
     const trimmed = raw.trim();
     const value = trimmed.startsWith('$')

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

@@ -1,3 +1,3 @@
-import type { LocatedSmartComment, RegisterContractsConflict, RegisterContractsOutputCandidate, RegisterContractsRoutine, RoutineSummary } from './types.js';
-export declare function findRegisterContractsConflicts(routine: RegisterContractsRoutine, summaries: Map<string, RoutineSummary>, hints: LocatedSmartComment[]): RegisterContractsConflict[];
+import type { LocatedSmartComment, RegisterContractsConflict, RegisterContractsOutputCandidate, RegisterContractsRoutine, RegisterContractsServiceRangeContract, RoutineSummary } from './types.js';
+export declare function findRegisterContractsConflicts(routine: RegisterContractsRoutine, summaries: Map<string, RoutineSummary>, hints: LocatedSmartComment[], serviceRanges?: readonly RegisterContractsServiceRangeContract[]): RegisterContractsConflict[];
 export declare function findCallerOutputCandidateObservations(routines: RegisterContractsRoutine[], summaries: Map<string, RoutineSummary>): RegisterContractsOutputCandidate[];

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

@@ -5,11 +5,11 @@ import { rstDispatcherServiceTargetNames, rstServiceTargetName, rstTargetName, }
 function unique(units) {
     return [...new Set(units)];
 }
-function boundaryTarget(routine, index, effect) {
+function boundaryTarget(routine, index, effect, serviceRanges = []) {
     const item = routine.instructions[index];
     return (callBoundaryTarget(effect) ??
         tailJumpBoundaryTarget(item, effect) ??
-        rstBoundaryTarget(routine, index, effect));
+        rstBoundaryTarget(routine, index, effect, serviceRanges));
 }
 function callBoundaryTarget(effect) {
     return effect.control.kind === 'call' && effect.control.target
@@ -36,23 +36,23 @@ function isTailJumpBoundary(item, effect) {
         effect.control.target !== undefined &&
         !effect.control.target.startsWith('.'));
 }
-function rstBoundaryTarget(routine, index, effect) {
+function rstBoundaryTarget(routine, index, effect, serviceRanges) {
     if (effect.control.kind !== 'rst' || effect.control.vector === undefined)
         return undefined;
     const target = rstTargetName(effect.control.vector);
     return {
-        targets: rstBoundaryTargets(routine, index, effect.control.vector, target),
+        targets: rstBoundaryTargets(routine, index, effect.control.vector, target, serviceRanges),
         conditional: false,
         subject: target,
     };
 }
-function rstBoundaryTargets(routine, index, vector, fallbackTarget) {
+function rstBoundaryTargets(routine, index, vector, fallbackTarget, serviceRanges) {
     const previous = routine.instructions[index - 1];
     const service = precedingCServiceName(previous);
     const numericService = precedingRegisterImmediateValue(previous, 'C');
     return [
         ...(numericService !== undefined ? [rstServiceTargetName(vector, String(numericService))] : []),
-        ...rstDispatcherServiceTargetNames(vector, (register) => precedingRegisterImmediateValue(previous, register)),
+        ...rstDispatcherServiceTargetNames(vector, (register) => precedingRegisterImmediateValue(previous, register), serviceRanges),
         ...(service ? [rstServiceTargetName(vector, service)] : []),
         fallbackTarget,
     ];
@@ -170,12 +170,12 @@ function liveSetsForRoutine(routine, summaries, hints = []) {
     }
     return { liveIn, liveOut };
 }
-function resolvedBoundariesForRoutine(routine, summaries) {
+function resolvedBoundariesForRoutine(routine, summaries, serviceRanges = []) {
     const out = [];
     for (let index = 0; index < routine.instructions.length; index += 1) {
         const item = routine.instructions[index];
         const effect = getZ80InstructionEffect(item.instruction);
-        const boundary = boundaryTarget(routine, index, effect);
+        const boundary = boundaryTarget(routine, index, effect, serviceRanges);
         if (!boundary)
             continue;
         const resolved = summaryForBoundary(boundary, summaries);
@@ -185,10 +185,10 @@ function resolvedBoundariesForRoutine(routine, summaries) {
     }
     return out;
 }
-export function findRegisterContractsConflicts(routine, summaries, hints) {
+export function findRegisterContractsConflicts(routine, summaries, hints, serviceRanges = []) {
     const conflicts = [];
     const { liveOut } = liveSetsForRoutine(routine, summaries, hints);
-    for (const { item, index, boundary, target, summary } of resolvedBoundariesForRoutine(routine, summaries)) {
+    for (const { item, index, boundary, target, summary } of resolvedBoundariesForRoutine(routine, summaries, serviceRanges)) {
         const accepted = new Set();
         for (const unit of hintUnitsForLine(hints, item.file, item.line))
             accepted.add(unit);

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

@@ -1,4 +1,4 @@
-import type { RegisterContractsUnit, RoutineSummary } from './types.js';
+import type { RegisterContractsServiceRangeContract, RegisterContractsUnit, RoutineSummary } from './types.js';
 export interface RegisterContractsProfileSummary {
     name: 'mon3';
     rst: Map<number, RoutineSummary>;
@@ -6,9 +6,14 @@ 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;
 export declare function rstServiceTargetName(vector: number, service: string): string;
-export declare function rstDispatcherServiceTargetNames(vector: number, selectorValue: (register: RegisterContractsUnit) => number | undefined): string[];
+export declare function rstDispatcherServiceTargetNames(vector: number, selectorValue: (register: RegisterContractsUnit) => number | undefined, configuredRanges?: readonly RegisterContractsServiceRangeContract[]): string[];
 export declare function getRegisterContractsProfile(name: 'mon3' | undefined): RegisterContractsProfileSummary | undefined;

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

@@ -89,21 +89,35 @@ 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) {
+export function rstDispatcherServiceTargetNames(vector, selectorValue, configuredRanges = []) {
     const mon3 = getRegisterContractsProfile('mon3');
     const dispatcher = mon3?.rstDispatchers.get(vector);
-    if (dispatcher === undefined)
-        return [];
-    const value = selectorValue(dispatcher.selector);
+    const selector = dispatcher?.selector ?? 'C';
+    const value = selectorValue(selector);
     if (value === undefined)
         return [];
-    const service = dispatcher.services.get(value);
-    return service ? [service.name] : [];
+    const service = dispatcher?.services.get(value);
+    const profileRangeService = dispatcher?.rangeServices?.find((entry) => rangeMatches(value, entry));
+    const configuredRangeServices = configuredRanges
+        .filter((entry) => entry.vector === vector && entry.selector === selector && rangeMatches(value, entry))
+        .map((entry) => entry.target);
+    return [
+        ...(service ? [service.name] : []),
+        ...(profileRangeService ? [profileRangeService.summary.name] : []),
+        ...configuredRangeServices,
+    ];
+}
+function rangeMatches(value, range) {
+    return value >= range.min && (range.max === undefined || value <= range.max);
 }
 export function getRegisterContractsProfile(name) {
     if (name !== 'mon3')
@@ -168,6 +182,17 @@ 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'],
+    };
     return {
         name: 'mon3',
         rst: new Map([
@@ -212,6 +237,7 @@ export function getRegisterContractsProfile(name) {
                         [16, scanKeys],
                         [18, matrixScan],
                         [54, parseMatrixScan],
+                        [0x53, bankCall],
                     ])),
                 },
             ],

package/dist/src/register-contracts/routine-summaries.d.ts

@@ -1,6 +1,6 @@
-import type { RegisterContractsRoutine, RoutineContract, RoutineSummary } from './types.js';
+import type { RegisterContractsRoutine, RegisterContractsServiceRangeContract, RoutineContract, RoutineSummary } from './types.js';
 export declare function summariesWithExternalContracts(summaries: RoutineSummary[], contracts: Map<string, RoutineContract>, routineNameSet: Set<string>): RoutineSummary[];
-export declare function inferRoutineSummariesToFixedPoint(routines: RegisterContractsRoutine[], contracts: Map<string, RoutineContract>, routineNameSet: Set<string>, profileSummaries: RoutineSummary[]): Array<{
+export declare function inferRoutineSummariesToFixedPoint(routines: RegisterContractsRoutine[], contracts: Map<string, RoutineContract>, routineNameSet: Set<string>, profileSummaries: RoutineSummary[], serviceRanges?: readonly RegisterContractsServiceRangeContract[]): Array<{
     routine: RegisterContractsRoutine;
     summary: RoutineSummary;
 }>;

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

@@ -55,9 +55,9 @@ function buildOptimisticInternalBoundarySummaryMap(routines) {
     }
     return out;
 }
-function summarizeRoutines(routines, contracts, boundarySummaryMap = new Map()) {
+function summarizeRoutines(routines, contracts, boundarySummaryMap = new Map(), serviceRanges = []) {
     return routines.map((routine) => {
-        const inferred = inferRoutineSummary(routine, boundarySummaryMap);
+        const inferred = inferRoutineSummary(routine, boundarySummaryMap, serviceRanges);
         const contract = contractForRoutine(routine, contracts);
         return { routine, summary: contract ? applyRoutineContract(inferred, contract) : inferred };
     });
@@ -82,13 +82,13 @@ function summaryFingerprint(summary) {
 function routineSummariesFingerprint(routineSummaries) {
     return routineSummaries.map((item) => summaryFingerprint(item.summary)).join('\n');
 }
-export function inferRoutineSummariesToFixedPoint(routines, contracts, routineNameSet, profileSummaries) {
-    let routineSummaries = summarizeRoutines(routines, contracts, buildOptimisticInternalBoundarySummaryMap(routines));
+export function inferRoutineSummariesToFixedPoint(routines, contracts, routineNameSet, profileSummaries, serviceRanges = []) {
+    let routineSummaries = summarizeRoutines(routines, contracts, buildOptimisticInternalBoundarySummaryMap(routines), serviceRanges);
     const maxPasses = Math.max(2, routines.length + 2);
     for (let pass = 0; pass < maxPasses; pass += 1) {
         const summaries = summariesWithExternalContracts(routineSummaries.map((item) => item.summary), contracts, routineNameSet);
         const boundarySummaryMap = buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries);
-        const nextRoutineSummaries = summarizeRoutines(routines, contracts, boundarySummaryMap);
+        const nextRoutineSummaries = summarizeRoutines(routines, contracts, boundarySummaryMap, serviceRanges);
         if (routineSummariesFingerprint(nextRoutineSummaries) ===
             routineSummariesFingerprint(routineSummaries)) {
             return nextRoutineSummaries;

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

@@ -1,9 +1,9 @@
 import type { Diagnostic } from '../model/diagnostic.js';
-import type { AnalyzeRegisterContractsOptions, RegisterContractsDirectCall, RegisterContractsRoutine, RoutineContract, RoutineSummary, RegisterContractsUnit, RegisterContractsOutputCandidate } from './types.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsDirectCall, RegisterContractsRoutine, RegisterContractsServiceRangeContract, RoutineContract, RoutineSummary, RegisterContractsUnit, RegisterContractsOutputCandidate } from './types.js';
 export declare function buildProfileSummaries(profileName: AnalyzeRegisterContractsOptions['registerContractsProfile']): RoutineSummary[];
 export declare function buildProfileSummaryLookup(profileName: AnalyzeRegisterContractsOptions['registerContractsProfile']): Map<string, RoutineSummary>;
 export declare function routineNames(routines: readonly RegisterContractsRoutine[]): string[];
-export declare function buildSummaries(routines: readonly RegisterContractsRoutine[], contractMap: Map<string, RoutineContract>, profileSummaries?: readonly RoutineSummary[]): RoutineSummary[];
+export declare function buildSummaries(routines: readonly RegisterContractsRoutine[], contractMap: Map<string, RoutineContract>, profileSummaries?: readonly RoutineSummary[], serviceRanges?: readonly RegisterContractsServiceRangeContract[]): RoutineSummary[];
 export declare function buildSummaryByName(routines: readonly RegisterContractsRoutine[], summaries: readonly RoutineSummary[], profileSummaries?: readonly RoutineSummary[]): Map<string, RoutineSummary>;
 export declare function withAcceptedOutputs(summaries: readonly RoutineSummary[], acceptedOutputCandidates: ReadonlyMap<string, RegisterContractsUnit[]> | undefined): RoutineSummary[];
 export declare function unknownBoundaryDiagnostics(directBoundaries: readonly RegisterContractsDirectCall[], knownRoutines: ReadonlySet<string>, severity?: Diagnostic['severity']): Diagnostic[];

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,17 +48,18 @@ 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;
 }
 export function routineNames(routines) {
     return routines.flatMap((routine) => boundaryLabels(routine));
 }
-export function buildSummaries(routines, contractMap, profileSummaries = []) {
+export function buildSummaries(routines, contractMap, profileSummaries = [], serviceRanges = []) {
     const names = routineNameSet(routines);
-    const routineSummaries = inferRoutineSummariesToFixedPoint([...routines], contractMap, names, [
-        ...profileSummaries,
-    ]);
+    const routineSummaries = inferRoutineSummariesToFixedPoint([...routines], contractMap, names, [...profileSummaries], serviceRanges);
     const summaries = routineSummaries.map((item) => item.summary);
     return summariesWithExternalContracts(summaries, contractMap, names);
 }

package/dist/src/register-contracts/summary-boundary.d.ts

@@ -1,2 +1,2 @@
-import type { RegisterContractsRoutine, RoutineSummary } from './types.js';
-export declare function boundarySummary(routine: RegisterContractsRoutine, index: number, summaries: ReadonlyMap<string, RoutineSummary>): RoutineSummary | undefined;
+import type { RegisterContractsRoutine, RegisterContractsServiceRangeContract, RoutineSummary } from './types.js';
+export declare function boundarySummary(routine: RegisterContractsRoutine, index: number, summaries: ReadonlyMap<string, RoutineSummary>, serviceRanges?: readonly RegisterContractsServiceRangeContract[]): RoutineSummary | undefined;

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

@@ -1,15 +1,15 @@
 import { getZ80InstructionEffect } from '../z80/effects.js';
 import { precedingCServiceName, precedingRegisterImmediateValue } from './boundaryHints.js';
 import { instructionHead } from './instruction-head.js';
-import { rstServiceTargetName, rstTargetName } from './profiles.js';
-export function boundarySummary(routine, index, summaries) {
+import { rstDispatcherServiceTargetNames, rstServiceTargetName, rstTargetName } from './profiles.js';
+export function boundarySummary(routine, index, summaries, serviceRanges = []) {
     const item = routine.instructions[index];
     if (!item)
         return undefined;
     const effect = getZ80InstructionEffect(item.instruction);
     return (callBoundarySummary(effect, summaries) ??
         jumpBoundarySummary(routine, item, effect, summaries) ??
-        rstBoundarySummary(routine, index, effect, summaries));
+        rstBoundarySummary(routine, index, effect, summaries, serviceRanges));
 }
 function callBoundarySummary(effect, summaries) {
     return effect.control.kind === 'call' && effect.control.target
@@ -28,20 +28,31 @@ function isExternalTailJump(routine, item, effect) {
         !effect.control.target.startsWith('.') &&
         !routine.labels.includes(effect.control.target));
 }
-function rstBoundarySummary(routine, index, effect, summaries) {
+function rstBoundarySummary(routine, index, effect, summaries, serviceRanges) {
     if (effect.control.kind !== 'rst' || effect.control.vector === undefined)
         return undefined;
-    return (rstServiceBoundarySummary(routine, index, effect.control.vector, summaries) ??
+    return (rstServiceBoundarySummary(routine, index, effect.control.vector, summaries, serviceRanges) ??
         summaries.get(rstTargetName(effect.control.vector)));
 }
-function rstServiceBoundarySummary(routine, index, vector, summaries) {
+function rstServiceBoundarySummary(routine, index, vector, summaries, serviceRanges) {
     const previous = routine.instructions[index - 1];
     const numericService = precedingRegisterImmediateValue(previous, 'C');
     if (numericService !== undefined) {
         const numericSummary = summaries.get(rstServiceTargetName(vector, String(numericService)));
         if (numericSummary !== undefined)
             return numericSummary;
+        const profileTarget = firstSummary(rstDispatcherServiceTargetNames(vector, (register) => (register === 'C' ? numericService : undefined), serviceRanges), summaries);
+        if (profileTarget !== undefined)
+            return profileTarget;
     }
     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.d.ts

@@ -1,3 +1,3 @@
 export { applyRoutineContract } from './summary-contract.js';
-import type { RegisterContractsRoutine, RoutineSummary } from './types.js';
-export declare function inferRoutineSummary(routine: RegisterContractsRoutine, boundarySummaries?: ReadonlyMap<string, RoutineSummary>): RoutineSummary;
+import type { RegisterContractsRoutine, RegisterContractsServiceRangeContract, RoutineSummary } from './types.js';
+export declare function inferRoutineSummary(routine: RegisterContractsRoutine, boundarySummaries?: ReadonlyMap<string, RoutineSummary>, serviceRanges?: readonly RegisterContractsServiceRangeContract[]): RoutineSummary;

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

@@ -1,4 +1,5 @@
 import { getZ80InstructionEffect } from '../z80/effects.js';
+import { instructionSuccessors, labelIndex } from './controlFlow.js';
 import { instructionHead } from './instruction-head.js';
 import { isAccumulatorSelfOperand, isImmediateZeroOperand, isPureTokenTransferInstruction, isRegisterOperand, } from './instruction-predicates.js';
 import { boundarySummary } from './summary-boundary.js';
@@ -91,7 +92,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 +101,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 +139,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 +154,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;
     }
@@ -135,6 +164,64 @@ function applyStackEffect(tokens, consumedProduced, intendedProduced, stack, sta
         state.hasUnknownStackEffect = true;
     }
 }
+function cloneStack(stack) {
+    return stack.map((entry) => ({
+        units: [...entry.units],
+        tokens: [...entry.tokens],
+    }));
+}
+function stackSignature(stack) {
+    return stack.map((entry) => entry.units.join('+')).join('/');
+}
+function emptyStackProofState() {
+    return { stackBalanced: true, hasUnknownStackEffect: false };
+}
+function boundaryFallsThrough(effect) {
+    return effect.control.kind === 'call' || effect.control.kind === 'rst';
+}
+function isTerminalExit(item, effect, successors) {
+    if (successors.length > 0)
+        return false;
+    if (effect.control.kind === 'return' && !effect.control.conditional)
+        return true;
+    return isOpaqueBoundary(item, effect) || effect.control.kind === 'fallthrough';
+}
+function proveStackDiscipline(routine, boundarySummaries, serviceRanges) {
+    const labels = labelIndex(routine);
+    const state = emptyStackProofState();
+    const seen = new Set();
+    const work = routine.instructions.length > 0 ? [{ index: 0, stack: [] }] : [];
+    while (work.length > 0) {
+        const current = work.pop();
+        const seenKey = `${current.index}|${stackSignature(current.stack)}`;
+        if (seen.has(seenKey))
+            continue;
+        seen.add(seenKey);
+        if (seen.size > 5000) {
+            state.hasUnknownStackEffect = true;
+            return state;
+        }
+        const item = routine.instructions[current.index];
+        if (item === undefined) {
+            if (current.stack.length !== 0)
+                state.stackBalanced = false;
+            continue;
+        }
+        const effect = getZ80InstructionEffect(item.instruction);
+        const stack = cloneStack(current.stack);
+        applyStackEffect(new Map(), new Set(), new Set(), stack, state, effect, isRoutineReturn(effect), boundarySummary(routine, current.index, boundarySummaries, serviceRanges));
+        const successors = instructionSuccessors(routine, current.index, effect, labels, {
+            boundaryFallthrough: boundaryFallsThrough(effect),
+        });
+        if (isTerminalExit(item, effect, successors) && stack.length !== 0) {
+            state.stackBalanced = false;
+        }
+        for (const successor of successors) {
+            work.push({ index: successor, stack: cloneStack(stack) });
+        }
+    }
+    return state;
+}
 function applyEffectWrites(tokens, consumedProduced, intendedProduced, directMayWrite, item, effect, transferWrites, instructionIntentOutputs, carryClearBeforeSbcHl) {
     for (const unit of effect.writes) {
         if (shouldIgnoreEffectWrite(unit, effect, transferWrites))
@@ -216,14 +303,14 @@ function createInferenceState() {
         },
     };
 }
-function instructionInferenceContext(routine, index, boundarySummaries) {
+function instructionInferenceContext(routine, index, boundarySummaries, serviceRanges) {
     const item = routine.instructions[index];
     const effect = getZ80InstructionEffect(item.instruction);
     const carryClearBeforeSbcHl = isCarryClearBeforeSbcHl(item, routine.instructions[index + 1]);
     return {
         item,
         effect,
-        knownBoundary: boundarySummary(routine, index, boundarySummaries),
+        knownBoundary: boundarySummary(routine, index, boundarySummaries, serviceRanges),
         carryClearBeforeSbcHl,
         expectedTerminalReturn: isRoutineReturn(effect),
         effectWrites: new Set(effect.writes),
@@ -255,12 +342,16 @@ function inferInstructionSummaryStep(state, context) {
     applyEffectWrites(state.tokens, state.consumedProduced, state.intendedProduced, state.directMayWrite, context.item, context.effect, transferWrites, context.instructionIntentOutputs, context.carryClearBeforeSbcHl);
     addInstructionIntentOutputs(state.intendedProduced, context.effectWrites, context.instructionIntentOutputs);
 }
-export function inferRoutineSummary(routine, boundarySummaries = new Map()) {
+export function inferRoutineSummary(routine, boundarySummaries = new Map(), serviceRanges = []) {
     const state = createInferenceState();
     for (let index = 0; index < routine.instructions.length; index += 1) {
-        inferInstructionSummaryStep(state, instructionInferenceContext(routine, index, boundarySummaries));
+        inferInstructionSummaryStep(state, instructionInferenceContext(routine, index, boundarySummaries, serviceRanges));
     }
     if (state.stack.length !== 0)
         state.stackState.stackBalanced = false;
+    const stackProof = proveStackDiscipline(routine, boundarySummaries, serviceRanges);
+    state.stackState.stackBalanced = stackProof.stackBalanced;
+    if (stackProof.hasUnknownStackEffect)
+        state.stackState.hasUnknownStackEffect = true;
     return buildRoutineSummary(routine, state.tokens, state.consumedProduced, state.intendedProduced, state.directMayWrite, state.mayRead, state.stackState);
 }

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 = {
@@ -54,6 +55,13 @@ export interface RoutineContract {
     preserves: RegisterContractsUnit[];
     complete?: boolean;
 }
+export interface RegisterContractsServiceRangeContract {
+    vector: number;
+    selector: RegisterContractsUnit;
+    min: number;
+    max?: number;
+    target: string;
+}
 export interface RegisterContractsInstruction {
     instruction: Z80Instruction;
     file: string;
@@ -161,6 +169,7 @@ export interface RoutineSummary {
     valueRelations: ValueRelation[];
     stackBalanced: boolean;
     hasUnknownStackEffect?: boolean;
+    consumesStackFrame?: RegisterContractsStackFrameUnit[];
     outputCandidates?: RegisterContractsUnit[];
 }
 export interface RegisterContractsOutputCandidate {
@@ -333,6 +342,7 @@ export interface AnalyzeRegisterContractsOptions {
     fixRegisterContracts?: boolean;
     registerContractsProfile?: 'mon3';
     interfaceContracts?: RoutineContract[];
+    interfaceServiceRanges?: RegisterContractsServiceRangeContract[];
     acceptedOutputCandidates?: ReadonlyMap<string, RegisterContractsUnit[]>;
     baselineReport?: RegisterContractsJsonReportModel;
     baselineFile?: string;

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

@@ -189,8 +189,10 @@ 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.
+RST service boundaries may name an exact selector value, such as
+`service rst $10 C $53 MON_BANK_CALL`, or a configured lower-bound range, such
+as `service rst $10 C >= $60 TECMATE_EXPANSION_SERVICE`. Comment lines are
+rejected so interface files stay machine-generated and deterministic.
 
 ## Effects, Summaries and Liveness
 
@@ -220,6 +222,25 @@ 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.
+
+Project-specific service ranges are not hardwired into AZM profiles. A project
+that owns `C >= $60` expansion services should declare that range in a local
+`.asmi` interface file. For TECM8-style expansion services, the conservative
+fallback should declare `C` as input, `A` and carry as outputs, and broad
+clobbers for `B,C,D,E,H,L,zero,sign,parity,halfCarry` unless a specific service
+has a tighter exact contract.
+
+Stack behaviour has a second path-sensitive proof pass for discipline only. It
+follows local branches inside one routine boundary, consumes known boundary
+stack frames, and accepts dispatcher arms that pop a shared entry frame before
+returning or tail-jumping. Register value inference remains summary-based.
+
 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.15",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {