@shapeshift-labs/frontier-lang-assembly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShapeShift Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @shapeshift-labs/frontier-lang-assembly
+
+Runtime-neutral assembly and low-level semantic merge evidence for Frontier Lang.
+
+This package scans assembly-like source into source-bound records for labels, directives, instructions, comments, register hints, flag hints, memory references, and branch/call targets. It is designed for merge review and projection evidence. It does not assemble source, emulate hardware, verify object code, or claim binary/timing equivalence.
+
+```js
+import { createAssemblySemanticMergeEvidence } from '@shapeshift-labs/frontier-lang-assembly';
+
+const evidence = createAssemblySemanticMergeEvidence(`
+Reset:
+  sep #$20
+  lda $2100
+  jsl LongCall
+  rtl
+`, { dialect: 'snes' });
+
+console.log(evidence.summary.instructions);
+console.log(evidence.proofGaps.map((gap) => gap.code));
+```
+
+## What It Captures
+
+- dialect profiles for generic assembly, x86, x86-64, arm64, riscv, LLVM IR, eBPF, 6502, 65816, SNES assembly, Z80, SM83, and m68k
+- labels and branch/call targets as source-bound symbolic records
+- directives such as `.include`, `.macro`, `.bank`, and conditional assembly as fail-closed proof gaps
+- rough register, flag, memory-reference, branch, call, and return hints
+- SNES/65816-specific gaps for processor mode, banked memory, memory-map, I/O-register, and cycle-timing proof
+
+## Boundary
+
+`frontier-lang-assembly` is a conservative evidence scanner. Target-specific assembler validation, object/binary decoding, debug symbols, emulator traces, cycle-accurate runtime proof, ABI proof, and final semantic merge admission belong above this package.
+
+High-level Frontier programs can lower toward assembly-like targets, but the reverse path is evidence-limited unless debug/source maps and semantic receipts are attached. This package gives Frontier a place to record what low-level source says about execution constraints without pretending those constraints are enough to recover all source-level meaning.

package/bench/smoke.mjs

@@ -0,0 +1,8 @@
+import { createAssemblySemanticMergeEvidence } from '../dist/index.js';
+
+const source = Array.from({ length: 1000 }, (_, index) => `L${index}:\n  lda #$${(index % 255).toString(16)}\n  sta $2100`).join('\n');
+const start = performance.now();
+const evidence = createAssemblySemanticMergeEvidence(source, { dialect: 'snes' });
+const elapsedMs = performance.now() - start;
+
+console.log(JSON.stringify({ instructions: evidence.summary.instructions, proofGaps: evidence.summary.proofGaps, elapsedMs: Number(elapsedMs.toFixed(3)) }));

package/dist/dialects.js

@@ -0,0 +1,52 @@
+const RegisterSets = Object.freeze({
+  generic: ['r0', 'r1', 'r2', 'r3', 'sp', 'fp', 'pc'],
+  x86: ['eax', 'ebx', 'ecx', 'edx', 'esi', 'edi', 'esp', 'ebp', 'eip', 'ax', 'bx', 'cx', 'dx', 'al', 'ah', 'bl', 'bh', 'cl', 'ch', 'dl', 'dh'],
+  x64: ['rax', 'rbx', 'rcx', 'rdx', 'rsi', 'rdi', 'rsp', 'rbp', 'rip', 'r8', 'r9', 'r10', 'r11', 'r12', 'r13', 'r14', 'r15', 'eax', 'ebx', 'ecx', 'edx'],
+  arm64: ['x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9', 'x10', 'x11', 'x12', 'x13', 'x14', 'x15', 'x16', 'x17', 'x18', 'x19', 'x20', 'x21', 'x22', 'x23', 'x24', 'x25', 'x26', 'x27', 'x28', 'x29', 'x30', 'sp', 'pc'],
+  riscv: ['x0', 'ra', 'sp', 'gp', 'tp', 't0', 't1', 't2', 's0', 'fp', 's1', 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'a7', 's2', 's3', 's4', 's5', 's6', 's7', 's8', 's9', 's10', 's11', 't3', 't4', 't5', 't6', 'pc'],
+  m6502: ['a', 'x', 'y', 'sp', 'pc', 'p'],
+  m65816: ['a', 'x', 'y', 's', 'd', 'db', 'pb', 'pc', 'p'],
+  z80: ['a', 'f', 'b', 'c', 'd', 'e', 'h', 'l', 'af', 'bc', 'de', 'hl', 'ix', 'iy', 'sp', 'pc'],
+  m68k: ['d0', 'd1', 'd2', 'd3', 'd4', 'd5', 'd6', 'd7', 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'a7', 'sp', 'pc', 'sr']
+});
+
+const FlowSets = Object.freeze({
+  generic: { branch: ['jmp', 'j', 'bra', 'br'], call: ['call', 'jsr', 'jal', 'bl', 'bsr'], ret: ['ret', 'rts', 'rtl', 'bx', 'jr'] },
+  x86: { branch: ['jmp', 'je', 'jne', 'jg', 'jge', 'jl', 'jle', 'ja', 'jb', 'jo', 'jno', 'js', 'jns'], call: ['call'], ret: ['ret', 'iret'] },
+  arm64: { branch: ['b', 'beq', 'bne', 'bgt', 'bge', 'blt', 'ble', 'cbz', 'cbnz', 'tbz', 'tbnz'], call: ['bl', 'blr'], ret: ['ret'] },
+  riscv: { branch: ['j', 'jal', 'beq', 'bne', 'blt', 'bge', 'bltu', 'bgeu'], call: ['call', 'jal', 'jalr'], ret: ['ret'] },
+  retro: { branch: ['bra', 'jmp', 'beq', 'bne', 'bpl', 'bmi', 'bcc', 'bcs', 'bvc', 'bvs', 'jp', 'jr', 'dbra'], call: ['jsr', 'jsl', 'call', 'bsr'], ret: ['rts', 'rtl', 'ret', 'rti', 'reti'] }
+});
+
+export const AssemblyDialectProfiles = Object.freeze([
+  profile('assembly', 'generic', ['asm', 's'], RegisterSets.generic, FlowSets.generic),
+  profile('x86', 'x86', [], RegisterSets.x86, FlowSets.x86),
+  profile('x86-64', 'x86', ['x64', 'x86_64', 'amd64'], RegisterSets.x64, FlowSets.x86),
+  profile('arm64', 'arm', ['aarch64'], RegisterSets.arm64, FlowSets.arm64),
+  profile('riscv', 'riscv', ['risc-v'], RegisterSets.riscv, FlowSets.riscv),
+  profile('llvm-ir', 'ir', ['ll', 'llvm'], ['ssa', 'ptr'], FlowSets.generic),
+  profile('ebpf', 'vm', ['bpf'], ['r0', 'r1', 'r2', 'r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10', 'fp', 'pc'], FlowSets.generic),
+  profile('asm-6502', 'retro', ['6502'], RegisterSets.m6502, FlowSets.retro),
+  profile('asm-65816', 'retro', ['65816'], RegisterSets.m65816, FlowSets.retro),
+  profile('snes-asm', 'retro', ['snes', 'sfc'], RegisterSets.m65816, FlowSets.retro, { hardware: 'snes' }),
+  profile('z80', 'retro', [], RegisterSets.z80, FlowSets.retro),
+  profile('sm83', 'retro', ['gbz80', 'gameboy'], RegisterSets.z80, FlowSets.retro),
+  profile('m68k', 'retro', ['68k'], RegisterSets.m68k, FlowSets.retro)
+]);
+
+export function normalizeAssemblyDialect(input = 'assembly') {
+  const wanted = String(input || 'assembly').toLowerCase();
+  for (const dialect of AssemblyDialectProfiles) {
+    if (dialect.id === wanted || dialect.aliases.includes(wanted)) return dialect.id;
+  }
+  return 'assembly';
+}
+
+export function findAssemblyDialect(input) {
+  const id = normalizeAssemblyDialect(input);
+  return AssemblyDialectProfiles.find((item) => item.id === id) ?? AssemblyDialectProfiles[0];
+}
+
+function profile(id, family, aliases, registers, flow, extra = {}) {
+  return Object.freeze({ id, family, aliases, registers, flow, ...extra });
+}

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+export interface SourceSpan {
+  readonly startOffset?: number;
+  readonly endOffset?: number;
+  readonly startLine?: number;
+  readonly startColumn?: number;
+  readonly endLine?: number;
+  readonly endColumn?: number;
+}
+
+export interface AssemblyProofGap {
+  readonly code: string;
+  readonly status: 'not-claimed';
+  readonly summary: string;
+  readonly failClosed: true;
+  readonly semanticEquivalenceClaim: false;
+  readonly binaryEquivalenceClaim: false;
+  readonly timingEquivalenceClaim: false;
+  readonly sourceSpan?: SourceSpan;
+}
+
+export interface AssemblyDialectProfile {
+  readonly id: string;
+  readonly family: string;
+  readonly aliases: readonly string[];
+  readonly registers: readonly string[];
+  readonly hardware?: string;
+  readonly flow: {
+    readonly branch: readonly string[];
+    readonly call: readonly string[];
+    readonly ret: readonly string[];
+  };
+}
+
+export interface AssemblyLabelRecord {
+  readonly kind: 'label';
+  readonly name: string;
+  readonly line: number;
+  readonly sourceSpan?: SourceSpan;
+}
+
+export interface AssemblyDirectiveRecord {
+  readonly kind: 'directive';
+  readonly name: string;
+  readonly args: readonly string[];
+  readonly line: number;
+  readonly sourceSpan?: SourceSpan;
+  readonly proofGaps: readonly AssemblyProofGap[];
+}
+
+export interface AssemblyInstructionRecord {
+  readonly kind: 'instruction';
+  readonly mnemonic: string;
+  readonly operands: readonly string[];
+  readonly line: number;
+  readonly sourceSpan?: SourceSpan;
+  readonly registersRead?: readonly string[];
+  readonly registersWritten?: readonly string[];
+  readonly flagsAffected?: readonly string[];
+  readonly memoryReferences?: readonly string[];
+  readonly controlFlow?: 'branch' | 'call' | 'return';
+  readonly branchTarget?: string;
+  readonly externalTarget?: boolean;
+  readonly proofGaps?: readonly AssemblyProofGap[];
+}
+
+export interface AssemblyCommentRecord {
+  readonly kind: 'comment';
+  readonly line: number;
+  readonly text: string;
+  readonly sourceSpan?: SourceSpan;
+}
+
+export type AssemblyRecord = AssemblyLabelRecord | AssemblyDirectiveRecord | AssemblyInstructionRecord;
+
+export interface AssemblyScanSummary {
+  readonly labels: number;
+  readonly directives: number;
+  readonly instructions: number;
+  readonly comments: number;
+  readonly branches: number;
+  readonly calls: number;
+  readonly returns: number;
+  readonly memoryReferences: number;
+  readonly proofGaps: number;
+}
+
+export interface AssemblySemanticScan {
+  readonly kind: 'frontier.lang.assemblySemanticScan';
+  readonly version: 1;
+  readonly sourcePath?: string;
+  readonly sourceHash: string;
+  readonly scanHash: string;
+  readonly dialect: AssemblyDialectProfile;
+  readonly records: readonly AssemblyRecord[];
+  readonly labels: readonly AssemblyLabelRecord[];
+  readonly directives: readonly AssemblyDirectiveRecord[];
+  readonly instructions: readonly AssemblyInstructionRecord[];
+  readonly comments: readonly AssemblyCommentRecord[];
+  readonly proofGaps: readonly AssemblyProofGap[];
+  readonly parser: { readonly status: 'ok' | 'needs-review'; readonly errors: readonly string[] };
+  readonly summary: AssemblyScanSummary;
+}
+
+export interface AssemblySemanticMergeEvidence {
+  readonly kind: 'frontier.lang.assemblySemanticMergeEvidence';
+  readonly version: 1;
+  readonly status: 'ready' | 'needs-review';
+  readonly sourcePath?: string;
+  readonly dialect: AssemblyDialectProfile;
+  readonly sourceHash: string;
+  readonly scanHash: string;
+  readonly records: readonly AssemblyRecord[];
+  readonly proofGaps: readonly AssemblyProofGap[];
+  readonly summary: AssemblyScanSummary;
+  readonly autoMergeClaim: false;
+  readonly semanticEquivalenceClaim: false;
+  readonly binaryEquivalenceClaim: false;
+  readonly timingEquivalenceClaim: false;
+}
+
+export interface AssemblySymbolQueryResult {
+  readonly labels: readonly AssemblyLabelRecord[];
+  readonly branchTargets: readonly {
+    readonly mnemonic: string;
+    readonly branchTarget?: string;
+    readonly sourceSpan?: SourceSpan;
+  }[];
+  readonly externalTargets: readonly {
+    readonly mnemonic: string;
+    readonly externalTarget?: boolean;
+    readonly sourceSpan?: SourceSpan;
+  }[];
+}
+
+export const AssemblyDialectProfiles: readonly AssemblyDialectProfile[];
+export function normalizeAssemblyDialect(input?: string): string;
+export function scanAssemblySource(sourceText: string, options?: { readonly sourcePath?: string; readonly sourceHash?: string; readonly dialect?: string }): AssemblySemanticScan;
+export function createAssemblySemanticMergeEvidence(sourceText: string, options?: { readonly sourcePath?: string; readonly sourceHash?: string; readonly dialect?: string }): AssemblySemanticMergeEvidence;
+export function summarizeAssemblyScan(scan: Pick<AssemblySemanticScan, 'labels' | 'directives' | 'instructions' | 'comments' | 'proofGaps'>): AssemblyScanSummary;
+export function queryAssemblySymbols(scan: Pick<AssemblySemanticScan, 'labels' | 'instructions'>): AssemblySymbolQueryResult;

package/dist/index.js

@@ -0,0 +1,289 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { findAssemblyDialect } from './dialects.js';
+export { AssemblyDialectProfiles, normalizeAssemblyDialect } from './dialects.js';
+
+export function scanAssemblySource(sourceText, options = {}) {
+  const dialect = findAssemblyDialect(options.dialect);
+  const sourceHash = options.sourceHash ?? hashSemanticValue({ kind: 'frontier.lang.assembly.source.v1', sourceText });
+  const lineStarts = computeLineStarts(sourceText);
+  const records = [];
+  const labels = [];
+  const directives = [];
+  const instructions = [];
+  const comments = [];
+  const proofGaps = [];
+  const lines = sourceText.split(/\n/);
+  let offset = 0;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const lineNumber = index + 1;
+    const split = splitComment(rawLine);
+    if (split.comment) comments.push({ kind: 'comment', line: lineNumber, text: split.comment.text, sourceSpan: sourceSpan(offset + split.comment.start, offset + rawLine.length, lineStarts) });
+    const code = split.code.trim();
+    const codeStart = rawLine.indexOf(split.code.trimStart());
+    if (code) parseCodeLine({ code, codeStart: Math.max(codeStart, 0), offset, lineStarts, lineNumber, dialect, records, labels, directives, instructions, proofGaps });
+    offset += rawLine.length + 1;
+  }
+
+  const scan = scanEnvelope({ sourcePath: options.sourcePath, sourceHash, dialect, records, labels, directives, instructions, comments, proofGaps });
+  return scan;
+}
+
+export function createAssemblySemanticMergeEvidence(sourceText, options = {}) {
+  const scan = scanAssemblySource(sourceText, options);
+  return {
+    kind: 'frontier.lang.assemblySemanticMergeEvidence',
+    version: 1,
+    status: scan.proofGaps.length ? 'needs-review' : 'ready',
+    sourcePath: options.sourcePath,
+    dialect: scan.dialect,
+    sourceHash: scan.sourceHash,
+    scanHash: scan.scanHash,
+    records: scan.records,
+    proofGaps: scan.proofGaps,
+    summary: scan.summary,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    binaryEquivalenceClaim: false,
+    timingEquivalenceClaim: false
+  };
+}
+
+export function summarizeAssemblyScan(scan) {
+  return {
+    labels: scan.labels?.length ?? 0,
+    directives: scan.directives?.length ?? 0,
+    instructions: scan.instructions?.length ?? 0,
+    comments: scan.comments?.length ?? 0,
+    branches: (scan.instructions ?? []).filter((item) => item.controlFlow === 'branch').length,
+    calls: (scan.instructions ?? []).filter((item) => item.controlFlow === 'call').length,
+    returns: (scan.instructions ?? []).filter((item) => item.controlFlow === 'return').length,
+    memoryReferences: (scan.instructions ?? []).reduce((sum, item) => sum + (item.memoryReferences?.length ?? 0), 0),
+    proofGaps: scan.proofGaps?.length ?? 0
+  };
+}
+
+export function queryAssemblySymbols(scan) {
+  return {
+    labels: scan.labels ?? [],
+    branchTargets: (scan.instructions ?? []).filter((item) => item.branchTarget).map((item) => ({ mnemonic: item.mnemonic, branchTarget: item.branchTarget, sourceSpan: item.sourceSpan })),
+    externalTargets: (scan.instructions ?? []).filter((item) => item.externalTarget).map((item) => ({ mnemonic: item.mnemonic, externalTarget: item.externalTarget, sourceSpan: item.sourceSpan }))
+  };
+}
+
+function parseCodeLine(ctx) {
+  let rest = ctx.code;
+  const labelMatch = /^([.$@A-Za-z_][\w.$@]*):/.exec(rest);
+  if (labelMatch) {
+    const span = sourceSpan(ctx.offset + ctx.codeStart, ctx.offset + ctx.codeStart + labelMatch[0].length, ctx.lineStarts);
+    const label = { kind: 'label', name: labelMatch[1], line: ctx.lineNumber, sourceSpan: span };
+    ctx.labels.push(label);
+    ctx.records.push(label);
+    rest = rest.slice(labelMatch[0].length).trim();
+    ctx.codeStart += ctx.code.indexOf(rest);
+    if (!rest) return;
+  }
+  if (/^[.%!][\w.$@]+/.test(rest)) return parseDirective(ctx, rest);
+  parseInstruction(ctx, rest);
+}
+
+function parseDirective(ctx, text) {
+  const [nameToken, ...parts] = text.split(/\s+/);
+  const name = nameToken.toLowerCase();
+  const args = splitOperands(parts.join(' '));
+  const record = {
+    kind: 'directive',
+    name,
+    args,
+    line: ctx.lineNumber,
+    sourceSpan: spanForText(ctx, text),
+    proofGaps: directiveGaps(name, ctx.dialect, spanForText(ctx, text))
+  };
+  ctx.directives.push(record);
+  ctx.records.push(record);
+  ctx.proofGaps.push(...record.proofGaps);
+}
+
+function parseInstruction(ctx, text) {
+  const match = /^([A-Za-z_.][\w.$@]*)(?:\s+(.*))?$/.exec(text);
+  if (!match) {
+    ctx.proofGaps.push(proofGap('assembly-parser-recovery', `Unable to classify assembly line ${ctx.lineNumber}.`, spanForText(ctx, text)));
+    return;
+  }
+  const mnemonic = match[1].toLowerCase();
+  const operands = splitOperands(match[2] ?? '');
+  const effects = instructionEffects(mnemonic, operands, ctx.dialect);
+  const gaps = instructionGaps(mnemonic, operands, ctx.dialect, spanForText(ctx, text));
+  const record = compactRecord({
+    kind: 'instruction',
+    mnemonic,
+    operands,
+    line: ctx.lineNumber,
+    sourceSpan: spanForText(ctx, text),
+    registersRead: effects.registersRead,
+    registersWritten: effects.registersWritten,
+    flagsAffected: effects.flagsAffected,
+    memoryReferences: effects.memoryReferences,
+    controlFlow: effects.controlFlow,
+    branchTarget: effects.branchTarget,
+    externalTarget: effects.externalTarget,
+    proofGaps: gaps.length ? gaps : undefined
+  });
+  ctx.instructions.push(record);
+  ctx.records.push(record);
+  ctx.proofGaps.push(...gaps);
+}
+
+function instructionEffects(mnemonic, operands, dialect) {
+  const registerHits = unique(operands.flatMap((operand) => registersIn(operand, dialect)));
+  const firstOperandRegisters = registersIn(operands[0] ?? '', dialect);
+  const writes = firstOperandRegisters.length && writesFirstOperand(mnemonic, dialect) ? firstOperandRegisters : implicitWrites(mnemonic, dialect);
+  const reads = unique(registerHits.filter((name) => !writes.includes(name)));
+  const flow = controlFlow(mnemonic, operands, dialect);
+  return {
+    registersRead: reads,
+    registersWritten: unique(writes),
+    flagsAffected: flagsAffected(mnemonic, dialect),
+    memoryReferences: operands.filter((operand) => isMemoryReference(operand, dialect)),
+    ...flow
+  };
+}
+
+function instructionGaps(mnemonic, operands, dialect, span) {
+  const gaps = [];
+  if (dialect.family === 'retro') gaps.push(proofGap('assembly-cycle-timing-boundary', `${dialect.id} timing requires assembler and emulator trace evidence.`, span));
+  if ((dialect.id === 'asm-65816' || dialect.id === 'snes-asm') && ['rep', 'sep', 'xce'].includes(mnemonic)) gaps.push(proofGap('assembly-processor-mode-boundary', '65816 width and emulation mode changes require mode-state evidence.', span));
+  if ((dialect.id === 'asm-65816' || dialect.id === 'snes-asm') && /(^|\W)(jsl|rtl|phb|plb|pea|per)(\W|$)/i.test([mnemonic, ...operands].join(' '))) gaps.push(proofGap('assembly-banked-memory-boundary', '65816 banked memory behavior requires bank-state evidence.', span));
+  if (dialect.hardware === 'snes' && operands.some((operand) => /\$21[0-9a-f]{2}|\$42[0-9a-f]{2}/i.test(operand))) gaps.push(proofGap('assembly-snes-io-boundary', 'SNES PPU/APU/CPU I/O registers require hardware trace evidence.', span));
+  return gaps;
+}
+
+function directiveGaps(name, dialect, span) {
+  const gaps = [];
+  if (/%?macro|\.macro|\.endmacro|\.rept|\.irp/.test(name)) gaps.push(proofGap('assembly-macro-expansion-boundary', 'Macro expansion requires assembler-specific evidence.', span));
+  if (/\.include|\.incbin|include|incbin/.test(name)) gaps.push(proofGap('assembly-include-boundary', 'Included assembly or binary content must be hashed and bound as evidence.', span));
+  if (/\.if|\.ifdef|\.ifndef|\.else|\.endif|%if|%ifdef|%endif/.test(name)) gaps.push(proofGap('assembly-conditional-assembly-boundary', 'Conditional assembly requires configured symbol evidence.', span));
+  if (dialect.family === 'retro' && /\.org|\.bank|\.segment|\.section/.test(name)) gaps.push(proofGap('assembly-memory-map-boundary', 'Retro memory placement requires linker/map evidence.', span));
+  return gaps;
+}
+
+function controlFlow(mnemonic, operands, dialect) {
+  const flow = dialect.flow ?? FlowSets.generic;
+  if (flow.ret.includes(mnemonic)) return { controlFlow: 'return' };
+  if (flow.call.includes(mnemonic)) return { controlFlow: 'call', branchTarget: cleanTarget(operands.at(-1)), externalTarget: isExternalTarget(operands.at(-1)) };
+  if (flow.branch.includes(mnemonic)) return { controlFlow: 'branch', branchTarget: cleanTarget(operands.at(-1)), externalTarget: isExternalTarget(operands.at(-1)) };
+  return {};
+}
+
+function writesFirstOperand(mnemonic, dialect) {
+  if (dialect.family === 'arm' || dialect.family === 'riscv') return !['cmp', 'tst', 'b', 'bl', 'ret'].includes(mnemonic);
+  if (dialect.family === 'retro') return ['sta', 'stx', 'sty', 'stz', 'lda', 'ldx', 'ldy', 'adc', 'sbc', 'and', 'ora', 'eor', 'inc', 'dec', 'asl', 'lsr', 'rol', 'ror'].includes(mnemonic);
+  return !['cmp', 'test', 'jmp', 'call', 'ret', 'push'].includes(mnemonic);
+}
+
+function implicitWrites(mnemonic, dialect) {
+  if (dialect.family === 'retro' && ['lda', 'adc', 'sbc', 'and', 'ora', 'eor', 'asl', 'lsr', 'rol', 'ror'].includes(mnemonic)) return ['a'];
+  if (dialect.family === 'retro' && mnemonic === 'ldx') return ['x'];
+  if (dialect.family === 'retro' && mnemonic === 'ldy') return ['y'];
+  return [];
+}
+
+function flagsAffected(mnemonic, dialect) {
+  const flaggy = ['add', 'adc', 'sub', 'sbc', 'cmp', 'cpx', 'cpy', 'test', 'and', 'ora', 'eor', 'asl', 'lsr', 'rol', 'ror', 'inc', 'dec', 'rep', 'sep'];
+  if (!flaggy.some((name) => mnemonic.startsWith(name))) return [];
+  if (dialect.family === 'retro') return ['n', 'v', 'z', 'c'];
+  if (dialect.family === 'x86') return ['zf', 'cf', 'sf', 'of'];
+  if (dialect.family === 'arm') return ['n', 'z', 'c', 'v'];
+  return ['condition'];
+}
+
+function registersIn(operand, dialect) {
+  const lower = String(operand).toLowerCase();
+  return dialect.registers.filter((reg) => new RegExp(`(^|[^\\w])${escapeRegExp(reg)}([^\\w]|$)`).test(lower));
+}
+
+function isMemoryReference(operand, dialect) {
+  const text = String(operand).trim();
+  if (/\[[^\]]+\]|\([^)]+\)/.test(text)) return true;
+  if (dialect.family === 'retro' && /\$[0-9a-f]{2,6}|<[^>]+>|>[^>]+/i.test(text)) return true;
+  return false;
+}
+
+function splitComment(line) {
+  const slash = line.indexOf('//');
+  const semi = line.indexOf(';');
+  const hash = /^\s*#/.test(line) ? line.search(/#/) : -1;
+  const starts = [slash, semi, hash].filter((index) => index >= 0);
+  if (!starts.length) return { code: line };
+  const start = Math.min(...starts);
+  return { code: line.slice(0, start), comment: { start, text: line.slice(start) } };
+}
+
+function splitOperands(text) {
+  if (!text.trim()) return [];
+  return text.split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function scanEnvelope(scan) {
+  const summary = summarizeAssemblyScan(scan);
+  return {
+    kind: 'frontier.lang.assemblySemanticScan',
+    version: 1,
+    parser: { status: scan.proofGaps.length ? 'needs-review' : 'ok', errors: [] },
+    scanHash: hashSemanticValue({ kind: 'frontier.lang.assembly.scan.v1', dialect: scan.dialect.id, records: scan.records.map(hashableRecord), proofGaps: scan.proofGaps.map((gap) => gap.code) }),
+    summary,
+    ...scan
+  };
+}
+
+function proofGap(code, summary, span) {
+  return compactRecord({ code, status: 'not-claimed', summary, failClosed: true, semanticEquivalenceClaim: false, binaryEquivalenceClaim: false, timingEquivalenceClaim: false, sourceSpan: span });
+}
+
+function sourceSpan(start, end, lineStarts) {
+  const from = positionAt(start, lineStarts);
+  const to = positionAt(end, lineStarts);
+  return { startOffset: start, endOffset: end, startLine: from.line, startColumn: from.column, endLine: to.line, endColumn: to.column };
+}
+
+function positionAt(offset, lineStarts) {
+  let line = 0;
+  while (line + 1 < lineStarts.length && lineStarts[line + 1] <= offset) line += 1;
+  return { line: line + 1, column: offset - lineStarts[line] + 1 };
+}
+
+function computeLineStarts(text) {
+  const starts = [0];
+  for (let index = 0; index < text.length; index += 1) if (text[index] === '\n') starts.push(index + 1);
+  return starts;
+}
+
+function spanForText(ctx, text) {
+  return sourceSpan(ctx.offset + ctx.codeStart, ctx.offset + ctx.codeStart + text.length, ctx.lineStarts);
+}
+
+function hashableRecord(record) {
+  return compactRecord({ kind: record.kind, name: record.name, mnemonic: record.mnemonic, operands: record.operands, line: record.line, proofGaps: record.proofGaps?.map((gap) => gap.code) });
+}
+
+function cleanTarget(value) {
+  return String(value ?? '').replace(/^[#<$>]+|[,)\]]+$/g, '') || undefined;
+}
+
+function isExternalTarget(value) {
+  const target = cleanTarget(value);
+  return Boolean(target && !/^[.$@A-Za-z_][\w.$@]*$/.test(target));
+}
+
+function unique(items) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+function compactRecord(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined && (!Array.isArray(value) || value.length)));
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@shapeshift-labs/frontier-lang-assembly",
+  "version": "0.1.0",
+  "description": "Runtime-neutral assembly and low-level semantic merge evidence for Frontier Lang.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "bench"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node test/smoke.mjs",
+    "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json",
+    "fuzz": "npm run build && node fuzz/smoke.mjs",
+    "bench": "npm run build && node bench/smoke.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run lint && npm test && npm run typecheck",
+    "pack:dry": "npm pack --dry-run",
+    "lint": "node scripts/lint.mjs"
+  },
+  "keywords": [
+    "frontier",
+    "semantic-merge",
+    "assembly",
+    "snes",
+    "low-level"
+  ],
+  "author": "ShapeShift Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/siliconjungle/-shapeshift-labs-frontier-lang-assembly.git"
+  },
+  "bugs": {
+    "url": "https://github.com/siliconjungle/-shapeshift-labs-frontier-lang-assembly/issues"
+  },
+  "homepage": "https://github.com/siliconjungle/-shapeshift-labs-frontier-lang-assembly#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@shapeshift-labs/frontier-lang-kernel": "0.3.12"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}