@jhlagado/azm 0.2.6 → 0.2.8

package/dist/src/{register-care → register-contracts}/routine-summaries.js

@@ -45,6 +45,16 @@ function buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries)
     }
     return boundarySummaryMap;
 }
+function buildOptimisticInternalBoundarySummaryMap(routines) {
+    const out = new Map();
+    for (const routine of routines) {
+        const summary = emptyRoutineSummary(routine.name);
+        for (const label of boundaryLabels(routine)) {
+            out.set(label, summary);
+        }
+    }
+    return out;
+}
 function summarizeRoutines(routines, contracts, boundarySummaryMap = new Map()) {
     return routines.map((routine) => {
         const inferred = inferRoutineSummary(routine, boundarySummaryMap);
@@ -73,7 +83,7 @@ function routineSummariesFingerprint(routineSummaries) {
     return routineSummaries.map((item) => summaryFingerprint(item.summary)).join('\n');
 }
 export function inferRoutineSummariesToFixedPoint(routines, contracts, routineNameSet, profileSummaries) {
-    let routineSummaries = summarizeRoutines(routines, contracts);
+    let routineSummaries = summarizeRoutines(routines, contracts, buildOptimisticInternalBoundarySummaryMap(routines));
     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);

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

@@ -0,0 +1,5 @@
+import type { LocatedSmartComment, RegisterContractsRoutine } from './types.js';
+export declare function collectPrecedingCommentBlock(routine: RegisterContractsRoutine, sourceTexts: ReadonlyMap<string, string>): {
+    comments: LocatedSmartComment[];
+    complete: boolean;
+};

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

@@ -0,0 +1,30 @@
+import { isCompactSourceCommentLine, parseSmartCommentLine } from './smartCommentParsing.js';
+function isCommentOnlyLine(line) {
+    return /^\s*;/.test(line);
+}
+export function collectPrecedingCommentBlock(routine, sourceTexts) {
+    const source = sourceTexts.get(routine.span.file);
+    if (source === undefined)
+        return { comments: [], complete: false };
+    const lines = source.split(/\r?\n/);
+    const rawBlock = [];
+    for (let index = routine.span.start.line - 2; index >= 0; index -= 1) {
+        const text = lines[index] ?? '';
+        if (!isCommentOnlyLine(text))
+            break;
+        rawBlock.push({ line: index + 1, text });
+    }
+    rawBlock.reverse();
+    let compactStart = rawBlock.length;
+    while (compactStart > 0 && isCompactSourceCommentLine(rawBlock[compactStart - 1]?.text ?? '')) {
+        compactStart -= 1;
+    }
+    const relevantBlock = compactStart < rawBlock.length ? rawBlock.slice(compactStart) : rawBlock;
+    return {
+        complete: compactStart < rawBlock.length,
+        comments: relevantBlock.flatMap((item) => {
+            const parsed = parseSmartCommentLine(item.text);
+            return parsed ? [{ file: routine.span.file, line: item.line, comment: parsed }] : [];
+        }),
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { SmartComment } from './types.js';
+export declare function parseSmartCommentLine(line: string): SmartComment | undefined;
+export declare function isCompactSourceCommentLine(line: string): boolean;

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

@@ -0,0 +1,80 @@
+import { expandCarrierList } from './carriers.js';
+const COMPACT_SOURCE_TAG_RE = /^;?\s*!\s*(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
+const COMPACT_SOURCE_LINE_RE = /^\s*;\s*!\s*(?:in|out|maybe-out|clobbers|preserves)(?:\s|$)/i;
+const CARRIER_RE = /^\{([^}]+)\}(?:\s+(.+))?$/;
+const CONTRACT_COMMENT_KINDS = new Set(['in', 'out', 'clobbers', 'preserves']);
+function parseCarrierPayload(rest) {
+    if (!rest)
+        return undefined;
+    const match = CARRIER_RE.exec(rest.trim());
+    if (match) {
+        const carriers = match[1]
+            .split(',')
+            .map((value) => value.trim())
+            .filter(Boolean);
+        const name = match[2]?.trim();
+        return { carriers, ...(name ? { name } : {}) };
+    }
+    const tokens = rest.trim().split(/\s+/u);
+    const carriers = [];
+    let consumed = 0;
+    for (const token of tokens) {
+        const cleaned = token.replace(/[.:;]+$/u, '');
+        const parts = cleaned
+            .split(',')
+            .map((value) => value.trim())
+            .filter(Boolean);
+        if (parts.length === 0 || !expandCarrierList(parts))
+            break;
+        carriers.push(...parts);
+        consumed += 1;
+    }
+    if (carriers.length === 0)
+        return undefined;
+    const name = tokens.slice(consumed).join(' ').trim();
+    return { carriers, ...(name ? { name } : {}) };
+}
+export function parseSmartCommentLine(line) {
+    const trimmed = line.trim();
+    const expectOut = parseExpectOutComment(trimmed);
+    if (expectOut !== undefined)
+        return expectOut;
+    const match = COMPACT_SOURCE_TAG_RE.exec(trimmed);
+    if (!match)
+        return undefined;
+    const tag = match[1].toLowerCase();
+    if (!CONTRACT_COMMENT_KINDS.has(tag))
+        return undefined;
+    return parseCarrierComment(tag, match[2]?.trim());
+}
+function parseExpectOutComment(trimmed) {
+    const expectOut = /^;?\s*expects\s+out\s+(.+)$/i.exec(trimmed);
+    if (expectOut === null)
+        return undefined;
+    return parseCarrierComment('expectOut', expectOut[1]?.trim());
+}
+function parseCarrierComment(kind, rest) {
+    const payload = parseCarrierPayload(rest);
+    if (!payload)
+        return undefined;
+    const carriers = expandCarrierList(payload.carriers);
+    if (!carriers || carriers.length === 0)
+        return undefined;
+    return buildCarrierComment(kind, carriers, payload.name);
+}
+function buildCarrierComment(kind, carriers, name) {
+    if (isUnnamedCarrierCommentKind(kind))
+        return { kind, carriers };
+    if (isNamedCarrierCommentKind(kind))
+        return { kind, carriers, ...(name ? { name } : {}) };
+    return undefined;
+}
+function isUnnamedCarrierCommentKind(kind) {
+    return kind === 'clobbers' || kind === 'preserves';
+}
+function isNamedCarrierCommentKind(kind) {
+    return kind === 'in' || kind === 'out' || kind === 'expectOut';
+}
+export function isCompactSourceCommentLine(line) {
+    return COMPACT_SOURCE_LINE_RE.test(line);
+}

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

@@ -0,0 +1,5 @@
+import type { LocatedSmartComment, RegisterContractsRoutine, RoutineContract } from './types.js';
+import { parseSmartCommentLine } from './smartCommentParsing.js';
+export { parseSmartCommentLine };
+export declare function parseSmartComments(sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>): LocatedSmartComment[];
+export declare function buildRoutineContracts(comments: LocatedSmartComment[], routines?: RegisterContractsRoutine[], sourceTexts?: ReadonlyMap<string, string>): Map<string, RoutineContract>;

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

@@ -0,0 +1,92 @@
+import { collectPrecedingCommentBlock } from './smartCommentBlocks.js';
+import { parseSmartCommentLine } from './smartCommentParsing.js';
+export { parseSmartCommentLine };
+export function parseSmartComments(sourceLineComments) {
+    const out = [];
+    for (const [file, comments] of sourceLineComments) {
+        for (const [line, text] of comments) {
+            const parsed = parseSmartCommentLine(`;${text}`);
+            if (parsed) {
+                out.push({ file, line, comment: parsed });
+            }
+        }
+    }
+    return out.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file)));
+}
+function appendUnique(items, values) {
+    for (const value of values) {
+        if (!items.includes(value)) {
+            items.push(value);
+        }
+    }
+}
+function applyContractComment(contract, comment) {
+    if (comment.kind === 'in')
+        appendUnique(contract.in, comment.carriers);
+    if (comment.kind === 'out')
+        appendUnique(contract.out, comment.carriers);
+    if (comment.kind === 'clobbers')
+        appendUnique(contract.clobbers, comment.carriers);
+    if (comment.kind === 'preserves')
+        appendUnique(contract.preserves, comment.carriers);
+}
+function hasContractContent(contract) {
+    return (contract.in.length > 0 ||
+        contract.out.length > 0 ||
+        contract.clobbers.length > 0 ||
+        contract.preserves.length > 0);
+}
+function buildImplicitRoutineContracts(routines, sourceTexts) {
+    const contracts = new Map();
+    for (const routine of routines) {
+        const docBlock = collectPrecedingCommentBlock(routine, sourceTexts);
+        if (docBlock.comments.some((item) => item.comment.kind === 'extern' || item.comment.kind === 'end')) {
+            continue;
+        }
+        const contract = {
+            name: routine.name,
+            in: [],
+            out: [],
+            clobbers: [],
+            preserves: [],
+            ...(docBlock.complete ? { complete: true } : {}),
+        };
+        for (const item of docBlock.comments) {
+            applyContractComment(contract, item.comment);
+        }
+        if (hasContractContent(contract)) {
+            contracts.set(routine.name, contract);
+        }
+    }
+    return contracts;
+}
+export function buildRoutineContracts(comments, routines = [], sourceTexts = new Map()) {
+    const contracts = new Map();
+    let current;
+    for (const item of comments) {
+        if (item.comment.kind === 'extern') {
+            current = {
+                name: item.comment.name,
+                in: [],
+                out: [],
+                clobbers: [],
+                preserves: [],
+            };
+            contracts.set(item.comment.name, current);
+            continue;
+        }
+        if (item.comment.kind === 'end') {
+            current = undefined;
+            continue;
+        }
+        if (current !== undefined) {
+            applyContractComment(current, item.comment);
+        }
+    }
+    for (const [name, contract] of buildImplicitRoutineContracts(routines, sourceTexts)) {
+        if (!contracts.has(name)) {
+            contracts.set(name, contract);
+        }
+    }
+    return contracts;
+}

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

@@ -0,0 +1,12 @@
+import type { Diagnostic } from '../model/diagnostic.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsDirectCall, RegisterContractsRoutine, 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 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[];
+export declare function unknownCallList(directBoundaries: readonly RegisterContractsDirectCall[], knownRoutines: ReadonlySet<string>): string[];
+export declare function buildOutputCandidateFixability(routines: readonly RegisterContractsRoutine[], outputCandidates: readonly RegisterContractsOutputCandidate[], autoFixableCandidateKeys: (routines: RegisterContractsRoutine[], outputCandidates: RegisterContractsOutputCandidate[]) => ReadonlySet<string>): ReadonlyMap<string, boolean>;
+export declare function outputCandidateKey(file: string, line: number, column: number): string;

package/dist/src/{register-care → register-contracts}/summaries.js

@@ -1,4 +1,4 @@
-import { getRegisterCareProfile } from './profiles.js';
+import { getRegisterContractsProfile } from './profiles.js';
 import { inferRoutineSummariesToFixedPoint, summariesWithExternalContracts, } from './routine-summaries.js';
 function unique(values) {
     const out = [];
@@ -20,7 +20,7 @@ function routineNameSet(routines) {
     return new Set(routines.flatMap((routine) => boundaryLabels(routine)));
 }
 export function buildProfileSummaries(profileName) {
-    const profile = getRegisterCareProfile(profileName);
+    const profile = getRegisterContractsProfile(profileName);
     if (profile === undefined) {
         return [];
     }
@@ -33,7 +33,7 @@ export function buildProfileSummaries(profileName) {
     ];
 }
 export function buildProfileSummaryLookup(profileName) {
-    const profile = getRegisterCareProfile(profileName);
+    const profile = getRegisterContractsProfile(profileName);
     const out = new Map();
     if (profile === undefined)
         return out;
@@ -104,13 +104,13 @@ export function withAcceptedOutputs(summaries, acceptedOutputCandidates) {
         return { ...summary, valueRelations };
     });
 }
-export function unknownBoundaryDiagnostics(directBoundaries, knownRoutines) {
+export function unknownBoundaryDiagnostics(directBoundaries, knownRoutines, severity = 'warning') {
     return directBoundaries
         .filter((boundary) => !knownRoutines.has(boundary.target))
         .map((boundary) => ({
-        severity: 'warning',
-        code: 'AZMN_REGISTER_CARE',
-        message: `Register-care cannot prove ${boundary.subject}; add a routine body or .asmi extern contract.`,
+        severity,
+        code: 'AZMN_REGISTER_CONTRACTS',
+        message: `Register contracts cannot prove ${boundary.subject}; add a routine body or .asmi extern contract.`,
         sourceName: boundary.file,
         line: boundary.line,
         column: boundary.column,

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

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

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

@@ -0,0 +1,40 @@
+import { getZ80InstructionEffect } from '../z80/effects.js';
+import { precedingCServiceName } from './boundaryHints.js';
+import { instructionHead } from './instruction-head.js';
+import { rstServiceTargetName, rstTargetName } from './profiles.js';
+export function boundarySummary(routine, index, summaries) {
+    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));
+}
+function callBoundarySummary(effect, summaries) {
+    return effect.control.kind === 'call' && effect.control.target
+        ? summaries.get(effect.control.target)
+        : undefined;
+}
+function jumpBoundarySummary(routine, item, effect, summaries) {
+    return isExternalTailJump(routine, item, effect)
+        ? summaries.get(effect.control.target)
+        : undefined;
+}
+function isExternalTailJump(routine, item, effect) {
+    return (effect.control.kind === 'jump' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
+        effect.control.target !== undefined &&
+        !effect.control.target.startsWith('.') &&
+        !routine.labels.includes(effect.control.target));
+}
+function rstBoundarySummary(routine, index, effect, summaries) {
+    if (effect.control.kind !== 'rst' || effect.control.vector === undefined)
+        return undefined;
+    return (rstServiceBoundarySummary(routine, index, effect.control.vector, summaries) ??
+        summaries.get(rstTargetName(effect.control.vector)));
+}
+function rstServiceBoundarySummary(routine, index, vector, summaries) {
+    const service = precedingCServiceName(routine.instructions[index - 1]);
+    return service ? summaries.get(rstServiceTargetName(vector, service)) : undefined;
+}

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

@@ -0,0 +1,2 @@
+import type { RoutineContract, RoutineSummary } from './types.js';
+export declare function applyRoutineContract(summary: RoutineSummary, contract: RoutineContract): RoutineSummary;

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

@@ -0,0 +1,45 @@
+import { FLAG_UNIT_LIST, contractOutRelation, unique, withImpliedFlagUnits, } from './summary-state.js';
+function relationKey(relation) {
+    return `${relation.out.join(',')}<- ${relation.from.join(',')}`;
+}
+function addContractRelation(out, relation) {
+    if (relation.out.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+export function applyRoutineContract(summary, contract) {
+    const contractIn = withImpliedFlagUnits(contract.in);
+    const contractOut = withImpliedFlagUnits(contract.out);
+    const contractClobbers = withImpliedFlagUnits(contract.clobbers);
+    const contractPreserves = withImpliedFlagUnits(contract.preserves);
+    const outputSet = new Set(contractOut);
+    const preservedSet = new Set(contractPreserves);
+    const inferredWrites = withImpliedFlagUnits(summary.mayWrite);
+    const baseMayWrite = contract.complete
+        ? inferredWrites.filter((unit) => FLAG_UNIT_LIST.includes(unit))
+        : inferredWrites;
+    const mayWrite = baseMayWrite.filter((unit) => !outputSet.has(unit) && !preservedSet.has(unit));
+    appendContractClobbers(mayWrite, contractClobbers, outputSet, preservedSet);
+    const mayWriteSet = new Set(withImpliedFlagUnits(mayWrite));
+    const preserved = unique([...summary.preserved, ...contractPreserves]).filter((unit) => !outputSet.has(unit) && !mayWriteSet.has(unit));
+    const valueRelations = [...summary.valueRelations];
+    const relation = contractOutRelation(contractIn, contractOut);
+    if (relation)
+        addContractRelation(valueRelations, relation);
+    return {
+        ...summary,
+        mayRead: unique(contractIn),
+        mayWrite,
+        preserved,
+        valueRelations,
+    };
+}
+function appendContractClobbers(mayWrite, contractClobbers, outputSet, preservedSet) {
+    for (const unit of contractClobbers) {
+        if (!outputSet.has(unit) && !preservedSet.has(unit) && !mayWrite.includes(unit)) {
+            mayWrite.push(unit);
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type Token } from './summary-state.js';
+import type { RegisterContractsRoutine, RegisterContractsUnit, RoutineSummary } from './types.js';
+export interface RoutineInferenceStackState {
+    stackBalanced: boolean;
+    hasUnknownStackEffect: boolean;
+}
+export declare function buildRoutineSummary(routine: RegisterContractsRoutine, tokens: ReadonlyMap<RegisterContractsUnit, Token>, consumedProduced: ReadonlySet<RegisterContractsUnit>, intendedProduced: ReadonlySet<RegisterContractsUnit>, directMayWrite: readonly RegisterContractsUnit[], mayRead: RegisterContractsUnit[], stackState: RoutineInferenceStackState): RoutineSummary;

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

@@ -0,0 +1,122 @@
+import { CONTRACT_FLAG_UNITS, GENERAL_REGISTER_UNITS, REGISTER_PAIRS, TRACKED_UNITS, tokenPreservesUnit, unique, } from './summary-state.js';
+function relationKey(relation) {
+    return `${relation.out.join(',')}<- ${relation.from.join(',')}`;
+}
+function addRelation(out, relation) {
+    if (relation.out.length === 0 || relation.from.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+function addContractRelation(out, relation) {
+    if (relation.out.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+function pairRelation(tokens, out) {
+    const from = [];
+    for (const unit of out) {
+        const token = tokens.get(unit);
+        if (!token || token.origin === 'unknown' || token.origin === 'produced')
+            return undefined;
+        from.push(token.origin);
+    }
+    if (out.every((unit, idx) => unit === from[idx]))
+        return undefined;
+    if (out.some((unit, idx) => unit === from[idx]))
+        return undefined;
+    return { out, from };
+}
+function producedPairRelation(tokens, consumedProduced, out) {
+    if (out.some((unit) => tokens.get(unit)?.origin !== 'produced' || consumedProduced.has(unit))) {
+        return undefined;
+    }
+    return { out, from: [] };
+}
+function addProducedPairOutputs(valueRelations, outputUnits, tokens, consumedProduced) {
+    for (const pair of REGISTER_PAIRS) {
+        const relation = producedPairRelation(tokens, consumedProduced, pair);
+        if (!relation)
+            continue;
+        addContractRelation(valueRelations, relation);
+        for (const unit of pair)
+            outputUnits.add(unit);
+    }
+}
+function singleUnitOutputRelation(unit, tokens, consumedProduced, intendedProduced) {
+    const current = tokens.get(unit);
+    const eligibleProduced = isProducedOutput(unit, current, intendedProduced);
+    const eligiblePreservedIntent = isPreservedIntentOutput(unit, current, intendedProduced);
+    if (!(eligibleProduced || eligiblePreservedIntent))
+        return undefined;
+    if (consumedProduced.has(unit))
+        return undefined;
+    return {
+        out: [unit],
+        from: eligiblePreservedIntent ? [unit] : [],
+    };
+}
+function isProducedOutput(unit, token, intendedProduced) {
+    if (token?.origin !== 'produced')
+        return false;
+    return GENERAL_REGISTER_UNITS.has(unit) || isProducedFlagOutput(unit, intendedProduced);
+}
+function isProducedFlagOutput(unit, intendedProduced) {
+    return CONTRACT_FLAG_UNITS.has(unit) && intendedProduced.has(unit);
+}
+function isPreservedIntentOutput(unit, token, intendedProduced) {
+    return token?.origin === unit && GENERAL_REGISTER_UNITS.has(unit) && intendedProduced.has(unit);
+}
+function addSingleUnitOutputs(valueRelations, outputUnits, tokens, consumedProduced, intendedProduced) {
+    for (const unit of TRACKED_UNITS) {
+        if (outputUnits.has(unit))
+            continue;
+        const relation = singleUnitOutputRelation(unit, tokens, consumedProduced, intendedProduced);
+        if (!relation)
+            continue;
+        addContractRelation(valueRelations, relation);
+        outputUnits.add(unit);
+    }
+}
+function collectPreservedAndMayWrite(tokens, outputUnits, directMayWrite) {
+    const preserved = [];
+    const mayWrite = [...directMayWrite];
+    for (const unit of TRACKED_UNITS) {
+        const current = tokens.get(unit);
+        if (tokenPreservesUnit(current, unit)) {
+            preserved.push(unit);
+            continue;
+        }
+        if (!outputUnits.has(unit))
+            mayWrite.push(unit);
+    }
+    return { preserved, mayWrite };
+}
+function addValueRelations(valueRelations, tokens) {
+    for (const pair of REGISTER_PAIRS) {
+        const relation = pairRelation(tokens, pair);
+        if (relation)
+            addRelation(valueRelations, relation);
+    }
+}
+export function buildRoutineSummary(routine, tokens, consumedProduced, intendedProduced, directMayWrite, mayRead, stackState) {
+    const valueRelations = [];
+    const outputUnits = new Set();
+    addProducedPairOutputs(valueRelations, outputUnits, tokens, consumedProduced);
+    addSingleUnitOutputs(valueRelations, outputUnits, tokens, consumedProduced, intendedProduced);
+    const { preserved, mayWrite } = collectPreservedAndMayWrite(tokens, outputUnits, directMayWrite);
+    addValueRelations(valueRelations, tokens);
+    mayRead.push(...valueRelations.flatMap((relation) => relation.from));
+    return {
+        name: routine.name,
+        mayRead: unique(mayRead),
+        mayWrite: unique(mayWrite),
+        preserved: unique(preserved),
+        valueRelations,
+        stackBalanced: stackState.stackBalanced,
+        hasUnknownStackEffect: stackState.hasUnknownStackEffect,
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { RegisterContractsInstruction, RegisterContractsUnit, ValueRelation } from './types.js';
+export declare const FLAG_UNIT_LIST: RegisterContractsUnit[];
+export declare const TRACKED_UNITS: RegisterContractsUnit[];
+export declare const GENERAL_REGISTER_UNITS: Set<RegisterContractsUnit>;
+export declare const CONTRACT_FLAG_UNITS: Set<RegisterContractsUnit>;
+export declare const STACK_POINTER_UNITS: Set<RegisterContractsUnit>;
+export declare const REGISTER_PAIRS: RegisterContractsUnit[][];
+export type Token = {
+    origin: RegisterContractsUnit;
+} | {
+    origin: 'produced';
+} | {
+    origin: 'unknown';
+};
+export declare function unique<T>(items: T[]): T[];
+export declare function isTrackedUnit(unit: RegisterContractsUnit): boolean;
+export declare function getRegisterUnits(name: string): RegisterContractsUnit[] | undefined;
+export declare function readToken(tokens: Map<RegisterContractsUnit, Token>, unit: RegisterContractsUnit): Token;
+export declare function semanticReadOrigins(tokens: Map<RegisterContractsUnit, Token>, units: RegisterContractsUnit[]): RegisterContractsUnit[];
+export declare function markProducedReadsConsumed(tokens: Map<RegisterContractsUnit, Token>, consumedProduced: Set<RegisterContractsUnit>, reads: RegisterContractsUnit[], writes: ReadonlySet<RegisterContractsUnit>, item?: RegisterContractsInstruction): void;
+export declare function tokenPreservesUnit(token: Token | undefined, unit: RegisterContractsUnit): boolean;
+export declare function withImpliedFlagUnits(units: RegisterContractsUnit[]): RegisterContractsUnit[];
+export declare function contractOutRelation(contractIn: RegisterContractsUnit[], contractOut: RegisterContractsUnit[]): ValueRelation | undefined;

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

@@ -0,0 +1,88 @@
+import { expandCarrierList } from './carriers.js';
+import { instructionHead } from './instruction-head.js';
+export const FLAG_UNIT_LIST = [
+    'carry',
+    'zero',
+    'sign',
+    'parity',
+    'halfCarry',
+];
+export const TRACKED_UNITS = [
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'H',
+    'L',
+    'IXH',
+    'IXL',
+    'IYH',
+    'IYL',
+    ...FLAG_UNIT_LIST,
+];
+export const GENERAL_REGISTER_UNITS = new Set([
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'H',
+    'L',
+]);
+export const CONTRACT_FLAG_UNITS = new Set(['carry', 'zero']);
+export const STACK_POINTER_UNITS = new Set(['SPH', 'SPL']);
+export const REGISTER_PAIRS = [
+    ['B', 'C'],
+    ['D', 'E'],
+    ['H', 'L'],
+];
+export function unique(items) {
+    return [...new Set(items)];
+}
+export function isTrackedUnit(unit) {
+    return TRACKED_UNITS.includes(unit);
+}
+export function getRegisterUnits(name) {
+    return expandCarrierList([name]);
+}
+export function readToken(tokens, unit) {
+    return tokens.get(unit) ?? { origin: 'unknown' };
+}
+export function semanticReadOrigins(tokens, units) {
+    const origins = [];
+    for (const unit of units) {
+        if (!isTrackedUnit(unit)) {
+            origins.push(unit);
+            continue;
+        }
+        const token = readToken(tokens, unit);
+        if (token.origin !== 'unknown' && token.origin !== 'produced')
+            origins.push(token.origin);
+    }
+    return origins;
+}
+export function markProducedReadsConsumed(tokens, consumedProduced, reads, writes, item) {
+    for (const unit of reads) {
+        if (!isTrackedUnit(unit) || writes.has(unit))
+            continue;
+        if (item !== undefined && instructionHead(item) === 'cp' && unit === 'A')
+            continue;
+        if (readToken(tokens, unit).origin === 'produced')
+            consumedProduced.add(unit);
+    }
+}
+export function tokenPreservesUnit(token, unit) {
+    return token?.origin === unit;
+}
+export function withImpliedFlagUnits(units) {
+    return unique(units);
+}
+export function contractOutRelation(contractIn, contractOut) {
+    if (contractOut.length === 0)
+        return undefined;
+    return {
+        out: contractOut,
+        from: contractIn.length === contractOut.length ? contractIn : [],
+    };
+}

package/dist/src/register-contracts/summary-token-transfer.d.ts

@@ -0,0 +1,3 @@
+import { type Token } from './summary-state.js';
+import type { RegisterContractsInstruction, RegisterContractsUnit } from './types.js';
+export declare function applyPureTokenTransfer(tokens: Map<RegisterContractsUnit, Token>, consumedProduced: Set<RegisterContractsUnit>, item: RegisterContractsInstruction): RegisterContractsUnit[];