M0: RetroAsset native asset foundation

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.github
+__pycache__
+*.py[cod]
+*.egg-info
+.pytest_cache
+.venv
+venv
+dist
+build
+tests

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - run: python -m unittest discover -s tests -v
+      - run: retroasset targets
+      - run: retroasset profile amiga-ocs
+      - run: retroasset profile ansi-cp437
+      - run: retroasset validate examples/amiga-ocs-sprite.json
+      - run: retroasset validate examples/ansi-cp437-screen.json
+      - run: retroasset export examples/amiga-ocs-checker.json --target amiga-ocs --format ilbm -o /tmp/checker.ilbm
+      - run: test -s /tmp/checker.ilbm
+      - name: Build OCI image
+        run: docker build -t retroasset:test .
+      - name: Smoke-test OCI CLI
+        run: docker run --rm retroasset:test targets
+      - name: Smoke-test OCI native export
+        run: |
+          mkdir -p /tmp/retroasset-oci
+          chmod 777 /tmp/retroasset-oci
+          docker run --rm \
+            -v "$PWD/examples:/work/input:ro" \
+            -v "/tmp/retroasset-oci:/work/output" \
+            retroasset:test export /work/input/amiga-ocs-checker.json \
+              --target amiga-ocs --format ilbm -o /work/output/checker.ilbm
+          test -s /tmp/retroasset-oci/checker.ilbm

.github/workflows/oci.yml

@@ -0,0 +1,42 @@
+name: OCI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    # Manual runs must not turn feature branches into published package sources.
+    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/ploos-as/retroasset
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/qualification.yml

@@ -0,0 +1,196 @@
+name: Emulator qualification
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [m0-foundation]
+    paths:
+      - "src/retroasset/c64prg.py"
+      - "src/retroasset/petscii.py"
+      - "src/retroasset/amiga.py"
+      - "qualification/**"
+      - ".github/workflows/qualification.yml"
+
+jobs:
+
+  amiga-m68k-q1:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e .
+      - name: Generate and embed ILBM fixtures
+        run: |
+          python qualification/generate_amiga_fixtures.py
+          python qualification/embed_amiga_fixtures.py
+      - name: Pull qualified Amiga development environment
+        run: docker pull ghcr.io/ploos-as/amiga-dev:edge
+      - name: Cross-build m68k guest verifier
+        run: |
+          mkdir -p qualification/runtime-input
+          docker run --rm \
+            --user "$(id -u):$(id -g)" \
+            -v "$PWD:/workspace:ro" \
+            -v "$PWD/qualification/runtime-input:/output" \
+            -w /workspace \
+            ghcr.io/ploos-as/amiga-dev:edge \
+            sh -ec 'amiga-check && m68k-amigaos-gcc -m68000 -Os -Wall -Wextra -Werror -DRETROASSET_EMBEDDED_FIXTURES qualification/amiga/ilbm_verify.c -o /tmp/ilbm-verify && file /tmp/ilbm-verify | tee /tmp/ilbm-file.txt && grep -Fq "AmigaOS loadseg()ble executable/binary" /tmp/ilbm-file.txt && cp /tmp/ilbm-verify /output/ilbm-verify'
+          cp qualification/amiga/amiga-runtime.json qualification/runtime-input/amiga-runtime.json
+          test -s qualification/runtime-input/ilbm-verify
+          test -s qualification/runtime-input/amiga-runtime.json
+      - name: Upload Q1 runtime payload
+        uses: actions/upload-artifact@v4
+        with:
+          name: retroasset-amiga-m68k-q1
+          path: qualification/runtime-input/
+          if-no-files-found: error
+
+
+  amiga-aros-q3:
+    needs: amiga-m68k-q1
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    env:
+      AMIGA_RUNTIME_IMAGE: ghcr.io/ploos-as/amiga-runtime:sha-fd7cc88
+    steps:
+      - name: Download Q1 payload
+        uses: actions/download-artifact@v4
+        with:
+          name: retroasset-amiga-m68k-q1
+          path: runtime-input
+      - name: Verify project contract
+        run: |
+          test -s runtime-input/amiga-runtime.json
+          jq -e '.schema == 1 and .architecture == "m68k"' runtime-input/amiga-runtime.json >/dev/null
+      - name: Pull immutable Amiga runtime
+        run: docker pull "$AMIGA_RUNTIME_IMAGE"
+      - name: Prepare AROS/m68k runtime
+        run: |
+          mkdir -p runtime-evidence runtime-aros
+          docker run --rm \
+            -v "$PWD/runtime-aros:/work/aros" \
+            -e AROS_RUNTIME_DIR=/work/aros \
+            "$AMIGA_RUNTIME_IMAGE" prepare-aros | tee runtime-evidence/aros-prepare.log
+          grep -Fq 'AROS m68k runtime prepared: PASS' runtime-evidence/aros-prepare.log
+      - name: Qualify RetroAsset ILBM payload in AROS/m68k
+        run: |
+          docker run --rm \
+            -v "$PWD/runtime-input:/work/input:ro" \
+            -v "$PWD/runtime-evidence:/work/evidence" \
+            -v "$PWD/runtime-aros:/work/aros" \
+            -e AROS_RUNTIME_DIR=/work/aros \
+            "$AMIGA_RUNTIME_IMAGE" qualify-contract /work/input --profile a1200-020-aros
+      - name: Upload AROS qualification evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: retroasset-amiga-aros-q3-evidence
+          path: runtime-evidence/
+          if-no-files-found: warn
+
+  c64-structural:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - run: python -m unittest tests.test_c64prg tests.test_c64prg_layout -v
+      - run: python qualification/generate_c64_fixture.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: retroasset-c64-fixture
+          path: qualification/generated/
+
+  c64-vice-open-roms:
+    runs-on: ubuntu-latest
+    needs: c64-structural
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - run: python qualification/generate_c64_fixture.py
+      - name: Install VICE and Open ROMs build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y vice git make gcc libpng-dev
+          x64sc --version
+      - name: Build redistributable C64 Open ROMs
+        run: |
+          git clone --depth 1 https://github.com/MEGA65/open-roms.git /tmp/open-roms
+          make -C /tmp/open-roms
+          find /tmp/open-roms/bin -maxdepth 1 -type f -print
+      - name: Locate Open ROMs
+        run: |
+          python qualification/find_open_roms.py /tmp/open-roms/bin qualification/generated/roms.env
+          cat qualification/generated/roms.env
+      - name: Run VICE qualification with Open ROMs
+        run: |
+          set -a
+          . qualification/generated/roms.env
+          set +a
+          xvfb-run -a x64sc \
+            -basic "$RETROASSET_BASIC_ROM" \
+            -kernal "$RETROASSET_KERNAL_ROM" \
+            -chargen "$RETROASSET_CHARGEN_ROM" \
+            -moncommands qualification/vice-monitor.txt \
+            -console
+      - name: Verify emulated RAM
+        run: python qualification/verify_c64.py
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: retroasset-c64-vice-open-roms-evidence
+          path: qualification/generated/
+
+  amiga-ilbm-consumer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - run: python -m unittest tests.test_amiga -v
+      - run: python qualification/generate_amiga_fixtures.py
+      - name: Build standalone ILBM verifier
+        run: |
+          cc -std=c99 -Wall -Wextra -Werror -O2 qualification/amiga/ilbm_verify.c -o qualification/generated/ilbm-verify-host
+          qualification/generated/ilbm-verify-host qualification/generated/amiga-uncompressed.ilbm qualification/generated/amiga-byterun1.ilbm | tee qualification/generated/ilbm-verify-host.log
+          grep -Fq 'RETROASSET_ILBM_UNCOMPRESSED_PASS' qualification/generated/ilbm-verify-host.log
+          grep -Fq 'RETROASSET_ILBM_BYTERUN1_PASS' qualification/generated/ilbm-verify-host.log
+      - name: Smoke-test embedded guest payload mode
+        run: |
+          python qualification/embed_amiga_fixtures.py
+          cc -std=c99 -Wall -Wextra -Werror -O2 -DRETROASSET_EMBEDDED_FIXTURES qualification/amiga/ilbm_verify.c -o qualification/generated/ilbm-verify-embedded-host
+          qualification/generated/ilbm-verify-embedded-host | tee qualification/generated/ilbm-verify-embedded-host.log
+          grep -Fq 'RETROASSET_ILBM_UNCOMPRESSED_PASS' qualification/generated/ilbm-verify-embedded-host.log
+          grep -Fq 'RETROASSET_ILBM_BYTERUN1_PASS' qualification/generated/ilbm-verify-embedded-host.log
+      - name: Install independent ILBM consumer
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y imagemagick
+          convert -version
+      - name: Decode generated ILBM files independently
+        run: |
+          identify qualification/generated/amiga-uncompressed.ilbm
+          identify qualification/generated/amiga-byterun1.ilbm
+          convert qualification/generated/amiga-uncompressed.ilbm qualification/generated/amiga-uncompressed.ppm
+          convert qualification/generated/amiga-byterun1.ilbm qualification/generated/amiga-byterun1.ppm
+          test -s qualification/generated/amiga-uncompressed.ppm
+          test -s qualification/generated/amiga-byterun1.ppm
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: retroasset-amiga-ilbm-consumer-evidence
+          path: qualification/generated/

ARCHITECTURE.md

@@ -0,0 +1,25 @@
+# RetroAsset architecture
+
+RetroAsset is an AI-assisted compiler/toolchain for native retro-computing assets.
+
+## Design principles
+
+1. **Hardware-authentic output.** A preview that looks retro is not sufficient; target validators decide whether an asset is valid.
+2. **Provider-independent AI.** Generation is an optional source stage. The core pipeline must work without any AI service.
+3. **Deterministic compilation.** Given a source asset, manifest and tool version, conversion and validation should be reproducible.
+4. **Targets own constraints.** Machine-specific rules live in target profiles and validators, not in the generic image pipeline.
+5. **Native output first.** PNG/SVG may be previews; ILBM, planar data, character cells and other native forms are first-class outputs.
+
+## Pipeline
+
+source -> import/generate -> RetroAsset IR -> transform -> target validator -> exporter -> native asset
+
+## Target families
+
+- raster: Amiga OCS/ECS/AGA, later Atari ST, EGA/VGA and Mac68k
+- character: ANSI/CP437, PETSCII, ATASCII
+- tile/sprite: machine-specific tile, Bob and sprite representations
+
+## M0
+
+M0 establishes the IR/manifest, CLI, target registry, Amiga OCS baseline validator and character-art extension points. AI backends are intentionally deferred.

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-alpine
+
+LABEL org.opencontainers.image.source="https://github.com/Ploos-AS/RetroAsset"
+LABEL org.opencontainers.image.description="RetroAsset native retro-asset compiler and validator"
+LABEL org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir . \
+    && addgroup -S retroasset \
+    && adduser -S -G retroasset retroasset
+
+RUN mkdir -p /work/input /work/output \
+    && chown retroasset:retroasset /work/output
+
+WORKDIR /work
+USER retroasset
+ENTRYPOINT ["retroasset"]
+CMD ["--help"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ploos AS
+
+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.