Web64-native c64lib Compatibility

Compatibility version: 3

Web64 provides a curated, browser-native adaptation of useful public c64lib contracts. It does not run the KickAssembler Java application, Gradle, Java plugins, native command processors, or the original build graph in the browser. An explicitly selected KickAssembler Compatibility Mode can compile only the evidence-backed direct-source subsets documented here. The adapted release contract is c64lib-compatibility-v3.json, and the direct-source checkpoint is c64lib-kick-direct-v1.json. The v1 and v2 adapted manifests remain available as frozen legacy contracts.

Authority and Scope

Planning and verification use these exact official revisions. Updating an upstream repository does not silently change Web64 behavior.

The official site and repositories remain the authority where names differ. Web64 records ambiguity in the compatibility ledger rather than guessing. Licensing and attribution are in C64LIB_COMPATIBILITY_NOTICES.md.

Compatibility Classifications

Every assessed facility is classified as native compatible, source compatible, semantically compatible, adapted Web64 implementation, requires ABI shim, replaced by an existing Web64 feature, compile-time only, import/conversion only, deferred, or intentionally unsupported. The generated ledger separately records API, source, binary, semantic, and workflow compatibility.

No general binary compatibility with KickAssembler output is claimed. A facility is not considered complete because an include parses or a similarly named routine exists; implemented entries require executable evidence.

Direct Kick Source Compatibility

Direct-source support is opt-in through KickAssembler Compatibility Mode (v5.25) and is classified independently from the established Web64-native adapters. The machine-readable authority is c64lib-kick-direct-v1.json.

This checkpoint proves exact Web64 output for the pinned minimal program, not general equivalence with every KickAssembler-produced binary. disableNMI parses in the imported source but is not executed by the P0 fixture and is classified accordingly. The optional KickAss.jar oracle and a broader licensed upstream corpus were unavailable for this gate, so the release makes no blanket c64lib source or upstream-binary claim.

Modules

Modules are selected per Build Target. Dependencies are automatic and runtime routines are linked only when referenced.

The Project tree exposes exact virtual sources under Web64 SDK > ASM includes > web64 > c64lib and headers under Web64 SDK > C headers > c64lib. Browsing a virtual file does not select its module. Compiling a compatibility include or header without the corresponding target module produces a diagnostic.

Assembly Surface

Web64 keeps hardware constants and bounded source forms that map safely to the native Web64 assembler. Adapted macros use explicit web64_c64lib_* names and remain the default compatibility path. Guided migration translates supported official invocations without requiring Kick mode. Separately, explicitly selected KickAssembler Compatibility Mode provides the governed v5.25 evaluator and adapters documented in KickAssembler Compatibility Mode, but direct c64lib compatibility is claimed only for facilities promoted by the pinned direct manifest. The presence or successful parsing of any other upstream include never promotes it automatically.

Common provides byte/word assignment, arithmetic, far branches, comparison, shifts, rotation, multiplication/addition, memory copy/fill, RLE decompression, and explicit hardware-call stack helpers. Chipset provides CIA and VIC-II declarations, memory configuration, VIC bank selection, PAL/NTSC detection, complete nine-bit raster values, raster IRQ helpers, display-mode setup, character transforms, and nine-bit sprite positioning. Text provides text increment/copy and screen/Color RAM movement primitives. Copper64 provides the four-byte list format and handler IDs 1 through 22.

.include "web64/c64lib/chipset.inc"

start:
    web64_c64lib_disable_cia_interrupts
    web64_c64lib_set_vic_bank C64LIB_BANK_1
    web64_c64lib_set_raster 250

C and Mixed-language ABI

The Web64 compiler owns one mixed-language ABI. Compatibility code does not introduce a second calling convention.

• web64-static-v0 preserves the established static-slot ABI for legacy projects.
• web64-stack-v1 uses the Web64 software stack for conforming automatic frames and wide or recursive calls.
• C symbols retain normal underscore decoration in assembly.
• Generated wrappers adapt only routines whose public register or memory contract differs from the selected ABI.
• C-to-assembly, assembly-to-C, callbacks, generated assets, linker symbols, and debugger provenance use the existing Web64 contracts.
• The guarded no-argument C callback helper saves stack-ABI zero page and call scratch, but does not make arbitrary C code raster-safe, reentrant, or NMI-safe.

All declared C compatibility routines are compile/link tested through the dependency-selected runtime. Register clobbers and interrupt safety remain routine-specific; callers must not infer preservation from short source. V3 adds the complete stateful Tile2 boundary and the Exomizer P39 decrunch call.

Zero Page and Memory Governance

Selected compatibility modules participate in the same declarative memory governance as the compiler, runtime, user assembly, assets, IRQ owners, and target linker. The registry records owner, range, width, lifetime, scratch/persistent use, interrupt visibility, reentrancy, overlay eligibility, and initialization.

The stack ABI owns $02-$17. Call-scoped compatibility scratch may overlay the compiler call scratch $fb-$fe only where lifetime rules prove that the uses cannot overlap. Copper64 stores its list pointer in installed code operands and has no persistent zero-page claim. Conflicts are diagnostics; Web64 does not silently relocate fixed hardware, VIC-visible data, vectors, or user reservations.

Build Targets govern origin, translation units, C mode, compatibility modules, and target format. Magic Desk CRT targets require origin $8000. PRG/test output is packaged with the selected entry point, while CRT output is split into deterministic 8 KiB CHIP banks with 0xff padding and an optional strict CBM80 bootstrap check.

Interrupt Interoperability

Copper64 V3 installs through the KERNAL IRQ vector $0314/$0315, owns the raster IRQ while active, and returns through the KERNAL path. Disable conflicting CIA sources before start; the Web64 helper also drains pending CIA interrupt flags, and Copper acknowledges a stale VIC raster request before enabling raster IRQs. Direct jump-table dispatch implements all 22 handlers. Handlers 1-7, 9, 11-15, and 18 use the upstream-style double-IRQ stabilizer. The stabilizer preserves the outer KERNAL stack pointer in private runtime state because the nested KERNAL IRQ prologue uses X itself. Handlers 16, 17, and 19 are line-sequenced; 8 and 10 are byte-semantic; and 20-22 synchronize to raster transitions. PAL uses the 6569 63-cycle contract and NTSC uses the 6567R8 65-cycle contract. Handler 21 is PAL-specific and handler 22 is NTSC-specific. Full raster bars remain explicitly badline-sensitive, matching the upstream warning; there is no blanket cycle guarantee beyond each handler's recorded class.

The guarded callback wrapper is pay-for-use. It preserves Web64-C stack ABI zero page around an approved no-argument callback. Nested interrupts, arbitrary runtime calls, banking changes, unbounded C execution, and cycle-critical callbacks remain prohibited unless the program establishes and verifies a stronger contract.

Browser-native Processors

The compatibility worker implements deterministic, cancellable byte transformations with transferable buffers:

• c64lib RLE encode/decode;
• interleave/deinterleave;
• Nybbler low/high-plane splitting, including optional high-plane normalization;
• packed-nibble helpers;
• record slicing;
• RGBA cut, split, extend, horizontal/vertical flip, and integer resolution reduction;
• Magic Desk CRT creation and parsing.
• GTS3-GTS5 song and GTI3-GTI5 instrument inspection/import, plus GTS5/GTI5 export through the W64SID v3 semantic model;
• lazy Exomizer 3.1.2 raw and in-memory P39 compression/decompression.

Existing Web64 systems replace Gradle processors for CharPad/CTM, SpritePad, Koala, native Char/Block/Map/Sprite assets, generated C headers, assembly includes, descriptors, dimensions, offsets, and byte counts. Those replacements use fixture-backed Web64 contracts instead of reproducing JVM task wrappers.

GoatTracker files are interchange codecs, not a second tracker project type. Import maps supported songs and instruments into editable W64SID v3 data, including typed orders, commands, instrument flags, and four raw tables. Export rebuilds the file from current W64SID state; it never substitutes a hidden stale source document. Untouched supported imports round-trip byte-for-byte. The gt2reloc compatibility option mapper covers relocation addresses, SFX/volume/optimization switches, ghost registers, and metadata as explicit options around the existing modular W64SID runtime. Exomizer is a lazy optional codec: selecting no Exomizer operation causes no Wasm load or build work. Arbitrary external command execution remains intentionally unsupported; Web64 never invokes host commands as a hidden fallback.

Tile2 Runtime

The Tile2 adapter consumes canonical Web64 Block and Map descriptors. It validates 2x2 blocks, one-byte indices, map bounds, and optional Color RAM/material planes, then emits the four 256-byte character planes, block metadata, map planes, and row offsets expected by the runtime. c64lib_tile2_init, explicit render, four directional scroll calls, and material lookup are available to C and assembly. Scrolling shifts the existing Screen and Color RAM regions and decodes only the newly exposed edge. A partial playfield uses startRow/endRow without changing the map-coordinate origin.

64spec Test Targets

The browser-native 64spec module provides reset; byte, 16/24/32-bit constant, byte-range, unsigned-order, masked-bit, processor-status, A/X/Y/XY, zero/nonzero, and explicit pass/fail assertions; and finish operations. Assembly assertions preserve caller A/X/Y/status where their contract observes transient CPU state. C exposes data-oriented equality, ordering, mask, and byte-range assertions. A test target must reference the result runtime. The artifact publishes the address of a seven-byte result block containing the W6 magic, status, passed count, and failed count so the emulator/debugger or automation can inspect deterministic machine results. Official hosted presentation/configuration options are replaced by target settings, the debugger, and machine-readable results rather than emulated as KickAssembler configuration objects.

.include "web64/c64lib/64spec.inc"

start:
    web64_64spec_reset
    lda #3
    web64_64spec_assert_a_equal 3
    web64_64spec_finish
    rts

Magic Desk CRT Targets

The Magic Desk module provides the $de00 bank register contract, a CBM80 bootstrap macro, register-ABI bank-copy entry points, and C wrappers. The browser-native writer validates bank range and uniqueness, writes standard CRT/CHIP headers, pads each bank, and parses generated images for verification.

Selecting a Magic Desk target changes only that target. Run lazily packages the current compile snapshot, attaches the CRT through the emulator cartridge API, and power-resets the C64. Save writes .crt. Ordinary PRG and test targets keep their existing paths. Live memory patching is deliberately disabled for a running banked cartridge.

Project Migration

Project Tree > Manage > Migrate c64lib Project performs non-destructive guided migration:

1. Inspect source and build conventions without changing the original.
2. Create a Web64-native project copy.
3. Preserve original files under legacy-c64lib/.
4. Translate recognized includes, constants, macro calls, compile-time text increment, and 64spec pseudo commands.
5. Infer modules and record each transformation.
6. Emit actionable diagnostics for unsupported hosted constructs.

The migration does not approximate KickAssembler structural DSL, compile-time host loaders, full Tile2 configuration DSL, memory-mode irqExit, dynamic copper handler selection, native GoatTracker/Exomizer tasks, or arbitrary Gradle commands.

Performance Isolation

Compatibility is strictly opt-in. No compatibility wrapper may become the default path for an existing native Web64 routine when the native path is smaller or faster. Shims remain boundary adapters.

Executable gates verify both Web64 ABIs:

• unselected modules add zero bytes;
• selected-but-unused modules add zero bytes and produce byte-identical output;
• native memcpy and other established lowerings are not redirected through compatibility wrappers;
• a referenced wrapper links only its dependency closure;
• fixed size ceilings prevent accidental helper or wrapper expansion;
• compatibility code does not link float, recursion, stack, or generic arithmetic helpers unless the source actually requires them.

These rules apply to native projects that do not request c64lib compatibility and to native operations inside compatibility-enabled projects.

Reference Projects and Evidence

• c64lib-common-asm.web64proj: pure assembly constants, macros, and runtime selection.
• c64lib-common-c.web64proj: pure C calls through the canonical ABI.
• c64lib-mixed.web64proj: C calling assembly and assembly calling C.
• c64lib-text-c.web64proj: C text output through the selected Text module.
• c64lib-tile2-scroll.web64proj: stateful 2x2 Tile2 initialization and automatic bounded scrolling with Screen/Color RAM edge refill.
• copper64-raster.web64proj: raster display list and IRQ ownership.
• c64lib-64spec.web64proj: machine-readable browser test target.
• c64lib-magic-desk.web64proj: CBM80 bootstrap and browser-generated CRT target.

Focused tests cover source pins, module dependency closure, includes and headers, all declared C routines, macro expansion, migration, processors, both ABIs, zero-page conflicts, target validation, CRT round trips, 64spec metadata, deterministic output, native-path byte identity, and compilation of every reference project. The direct-source checkpoint additionally uses test/fixtures/kick-assembler/language/c64lib-direct-p0.asm, verbatim upstream sources under test/fixtures/kick-assembler/upstream/c64lib/chipset/e91455ba6f4f87e2d0d4e7604215e52db9e96ee2/, and test/web64-kick-assembler-compatibility.test.mjs to prove source integrity, exact bytes and symbols, provenance, replay, and adapted-macro equivalence.

Explicit Unsupported Boundaries

• The KickAssembler Tile2 configuration DSL is not emulated; use the Web64 config record or canonical asset adapter.
• Copper contracts are handler-specific. Byte-semantic handlers and badline-sensitive raster bars are not advertised as universally cycle-stable.
• GoatTracker is not bundled; W64SID remains authoritative after import. Standard single-SID GoatTracker 2 is supported, while stereo/multi-SID variants remain explicitly deferred.
• Exomizer compatibility is limited to the fixture-backed 3.1.2 raw/in-memory P39 surface and its declared options.
• Arbitrary Gradle/JVM/native command processors are intentionally unsupported.
• Direct Kick source compatibility is limited to facilities explicitly promoted by c64lib-kick-direct-v1.json; general c64lib source coverage and upstream KickAssembler binary compatibility remain unclaimed.

V3 / Web64 IDE 1.0 Completion Rule

V3 closes only when the ordered stage gate reports Foundation, Tile2, GoatTracker/gt2reloc, Exomizer, Copper PAL/NTSC, and Release as closed. A later stage cannot begin while an earlier stage exposes an unresolved contract defect that invalidates downstream assumptions. Native-path purity remains a release invariant: compatibility modules cannot alter PRG bytes, compiler decisions, symbols, or dependencies unless selected and referenced.