diff --git a/discussion/lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md b/discussion/lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md new file mode 100644 index 00000000..b21a5a48 --- /dev/null +++ b/discussion/lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md @@ -0,0 +1,85 @@ +--- +id: LSN-0082 +ticket: packer-runtime-graphics-conformance +title: Packer Contracts and CI Failure Evidence +created: 2026-10-16 +tags: [packer, studio, testing, jenkins] +--- + +# Packer Contracts and CI Failure Evidence + +## Original problem and scope + +A broad runtime-readiness audit suggested graphics integration qualification, +but historical review did not establish a new asset format migration. Existing +Studio work already covered RGBA8888, scene identity and variable palettes. +The actual opportunity was to strengthen producer-boundary evidence and ensure +CI preserved useful results when tests failed. + +Owner: packer; transverse owner: Studio Gradle/Jenkins infrastructure. The user +explicitly excluded runtime provisioning in Jenkins and all new automated +runtime tests, including local ones. Existing games remain the manual integrated +verification method. This lesson does not claim those games were run. + +## Consolidated decision and implementation + +The packer's ordinary Java/JUnit suite now checks complete serialized GLYPH +payloads for tile sizes 8/16/32 and palette counts 1/3/64, using independently +authored hex expectations. Alpha, ordinary index zero and high-first nibble +order are compared as bytes. A complete four-layer SCENE fixture covers +little-endian identity, parallax, flags/flips and decoded-size accounting. +An out-of-range palette cannot publish a new artifact. + +A mixed-asset test reads the embedded header of assets.pa, checks sidecar +agreement and proves that all payload slices cover the file contiguously. +Two GLYPH preloads use slots 0/1 while SCENE uses its own slot 0; a fourth +asset is deliberately not preloaded. AssetId 16909060 remains the scene's +cold dependency even though the glyph preload slot is 1. These identities +must not be conflated. + +Jenkins now uses the repository wrapper, headless JVMs and a separate clean +stage. Verification uses --continue: independent tests and reports complete, +but Gradle still fails on test failure. Unconditional post handling isolates +JUnit, coverage, HTML and archive publishers. Missing evidence after a successful +verification is an error; failed preparation does not publish old reports. +Existing coverage thresholds and their UNSTABLE policy remain unchanged. +No production writer change was necessary. + +## Evidence and limits + +Studio base: 13c0ababbb0ff8623eb4df671729a891788b1ab1. Contract reference: +runtime f7d7c167531bb662a1af9d73fc326bb476bf8aa7. Validation on 2026-10-16: + +- Packer suite: 119 tests passed, zero skips; five new contract cases included. +- Ordinary headless repository run: 897 tests, two failures, 13 existing skips. + Consolidated JaCoCo XML and HTML were generated despite test failure. +- Failures in unchanged files: PbsGradleDependencyAllowlistTest rejects the + existing build-pipeline testImplementation PBS dependency; McpContractTest + rejects an existing tool exampleArguments contract. The complete repository + test gate is not green; these failures were not suppressed by this change. +- Groovy 4.0.29 parsed the Jenkinsfile. Seven local step-double scenarios passed: + success, test failure, publisher failure, missing contract report, absent + reports on success/failure and clean failure. This does not validate actual + controller plugins or constitute a Jenkins job run. +- git diff --check and discussion validate passed. + +No runtime invocation, automated frame comparison or manual gameplay was +performed. Producer bytes passing these assertions do not prove live loading +or presentation. Report manual game/revision/actions/results only after play. + +## Pitfalls + +- Deriving expected bytes through the production writer makes an oracle circular. +- Checking only exported JSON misses corruption in the embedded artifact header. +- Publishing reports only after a successful shell step hides failure diagnostics. +- Allowing empty reports on successful verification can turn absent execution into + apparent success. Allow absence only when the build already failed. +- A broad contract corpus is not a reason to duplicate existing tests or port a + runtime decoder into Java. Keep checks at the producer's actual output boundary. + +## References + +- [Fixture interpretation and commands](../../../prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md). +- [CI commands and failure behavior](../../../files/config/README.md). +- [Build artifact specification](../../../docs/specs/packer/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md). +- Completed workflow provenance: AGD-0079, DEC-0066, PLN-0145 (housekept after implementation). diff --git a/files/config/Jenkinsfile b/files/config/Jenkinsfile index 707b94b0..c9de926e 100644 --- a/files/config/Jenkinsfile +++ b/files/config/Jenkinsfile @@ -1,68 +1,92 @@ pipeline { agent any - tools { - gradle 'gradle-9.3.1' - } - environment { GRADLE_USER_HOME = '/var/jenkins_home/.gradle' GRADLE_OPTS = '-Dorg.gradle.parallel=true -Dorg.gradle.caching=true' + JAVA_TOOL_OPTIONS = '-Djava.awt.headless=true' JAVA_OPTS = '-Xmx2g' + TESTS_STARTED = 'false' + VERIFICATION_SUCCEEDED = 'false' } stages { - stage('Build') { + stage('Clean') { steps { + // A separate successful clean prevents publishing a previous build's reports. + withGradle { + sh './gradlew clean --no-daemon --console=plain' + } + } + } + stage('Tests and coverage') { + steps { + script { env.TESTS_STARTED = 'true' } withChecks(name: 'Test', includeStage: true) { withGradle { - sh """ - gradle \ - clean \ - test \ - jacocoTestReport \ - --parallel \ - --max-workers=2 \ - --build-cache \ - --no-daemon - """ + // --continue finishes independent tests/reports but retains a nonzero exit on failure. + sh './gradlew test jacocoTestReport --continue --parallel --max-workers=2 --build-cache --no-daemon --console=plain' } - junit testResults: '**/build/test-results/test/TEST-*.xml' - } - withChecks(name: 'JaCoCo Coverage', includeStage: false) { - recordCoverage(tools: [[parser: 'JACOCO', pattern: "build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml"]], - id: 'jacoco', - name: 'JaCoCo Coverage', - checksName: 'JaCoCo Coverage', - sourceDirectories: [[path: 'glob:**/src/main/java']], - sourceCodeEncoding: 'UTF-8', - sourceCodeRetention: 'EVERY_BUILD', - qualityGates: [ - [threshold: 50.0, metric: 'CLASS', baseline: 'PROJECT', criticality: 'UNSTABLE'], - [threshold: 50.0, metric: 'METHOD', baseline: 'PROJECT', criticality: 'UNSTABLE'], - [threshold: 50.0, metric: 'LINE', baseline: 'PROJECT', criticality: 'UNSTABLE'], - [threshold: 50.0, metric: 'INSTRUCTION', baseline: 'PROJECT', criticality: 'UNSTABLE'], - [threshold: 40.0, metric: 'BRANCH', baseline: 'PROJECT', criticality: 'UNSTABLE']]) } + script { env.VERIFICATION_SUCCEEDED = 'true' } } - } // Test - - stage('Reports') { - steps { - script { - // archiveArtifacts artifacts: '**/coverage-sources.zip', allowEmptyArchive: false, fingerprint: false, onlyIfSuccessful: false - publishHTML (target: [ - allowMissing: true, - alwaysLinkToLastBuild: false, - keepAll: true, - reportDir: "build/reports/jacoco/jacocoTestReport/html", - reportFiles: 'index.html', - reportName: 'Coverage Report' - ]) - // def pmd = scanForIssues tool: [$class: 'Pmd'], pattern: 'lib/build/reports/pmd/*.xml' - // publishIssues issues: [pmd] - } - } - } // Reports + } } -} \ No newline at end of file + + post { + always { + script { + if (env.TESTS_STARTED == 'true') { + // Isolate publishers so a failed publisher does not suppress the other diagnostics. + catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') { + junit testResults: '**/build/test-results/test/TEST-*.xml', + allowEmptyResults: env.VERIFICATION_SUCCEEDED != 'true' + if (env.VERIFICATION_SUCCEEDED == 'true' && !fileExists('prometeu-packer/prometeu-packer-v1/build/test-results/test/TEST-p.packer.services.PackerAssetContractTest.xml')) { + error 'Successful verification is missing the packer contract test report.' + } + } + catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') { + if (fileExists('build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml')) { + withChecks(name: 'JaCoCo Coverage', includeStage: false) { + recordCoverage(tools: [[parser: 'JACOCO', pattern: 'build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml']], + id: 'jacoco', + name: 'JaCoCo Coverage', + checksName: 'JaCoCo Coverage', + sourceDirectories: [[path: 'glob:**/src/main/java']], + sourceCodeEncoding: 'UTF-8', + sourceCodeRetention: 'EVERY_BUILD', + qualityGates: [ + [threshold: 50.0, metric: 'CLASS', baseline: 'PROJECT', criticality: 'UNSTABLE'], + [threshold: 50.0, metric: 'METHOD', baseline: 'PROJECT', criticality: 'UNSTABLE'], + [threshold: 50.0, metric: 'LINE', baseline: 'PROJECT', criticality: 'UNSTABLE'], + [threshold: 50.0, metric: 'INSTRUCTION', baseline: 'PROJECT', criticality: 'UNSTABLE'], + [threshold: 40.0, metric: 'BRANCH', baseline: 'PROJECT', criticality: 'UNSTABLE']]) + } + } else if (env.VERIFICATION_SUCCEEDED == 'true') { + error 'Successful verification is missing the consolidated JaCoCo XML report.' + } else { + echo 'Verification failed before consolidated coverage was available; preserving available test reports.' + } + } + catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') { + publishHTML(target: [ + allowMissing: env.VERIFICATION_SUCCEEDED != 'true', + alwaysLinkToLastBuild: false, + keepAll: true, + reportDir: 'build/reports/jacoco/jacocoTestReport/html', + reportFiles: 'index.html', + reportName: 'Coverage Report' + ]) + } + catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') { + archiveArtifacts artifacts: '**/build/test-results/test/**, **/build/reports/tests/test/**, **/build/reports/jacoco/**', + allowEmptyArchive: env.VERIFICATION_SUCCEEDED != 'true', + onlyIfSuccessful: false + } + } else { + echo 'Preparation did not complete; no current test run to publish. See the build console for diagnostics.' + } + } + } + } +} diff --git a/files/config/README.md b/files/config/README.md new file mode 100644 index 00000000..6ced9b9b --- /dev/null +++ b/files/config/README.md @@ -0,0 +1,57 @@ +# Studio Jenkins verification + +`Jenkinsfile` uses the checked-in Gradle wrapper (currently 9.3.1). A compatible +Java installation must be available to launch Gradle; project conventions select +Java 21 for compilation/tests. The pipeline retains its existing Gradle cache +location, worker limit and installed Jenkins report plugins. It does not require +a named Jenkins Gradle installation. + +The build runs on a Unix agent with Java and dependency/cache access. It sets +`JAVA_TOOL_OPTIONS=-Djava.awt.headless=true` for Gradle and test JVMs. No display, +runtime binary, sibling runtime checkout, runtime download/build, or new Jenkins +plugin is required by the packer contract suite. + +## Commands + +```sh +export JAVA_TOOL_OPTIONS=-Djava.awt.headless=true +./gradlew clean --no-daemon --console=plain +./gradlew test jacocoTestReport --continue --parallel --max-workers=2 --build-cache --no-daemon --console=plain +``` + +Clean is a separate stage: when it fails, old reports must not be published as a +new test run. Gradle `--continue` lets independent tasks and reports finish after +a test failure; it does not turn a failing command into success. Runtime/desktop +opt-in test tasks are not invoked. The ordinary packer `test` task includes +`PackerAssetContractTest` without skips or a runtime fallback. + +## Failure reporting + +The unconditional post block publishes available JUnit, consolidated JaCoCo XML, +HTML and archived test/coverage reports after a failed verification command. +Each publisher is isolated so one publisher error does not prevent the others +from being attempted. The build console retains compilation/setup diagnostics. + +An otherwise successful verification must produce JUnit results, the packer +contract suite report, consolidated JaCoCo XML and HTML. Missing successful-build +evidence fails publication. A failed compilation may have no reports: the +original build failure remains authoritative and available diagnostics are still +preserved. A failed clean does not publish potentially stale artifacts. + +Coverage thresholds are unchanged: CLASS/METHOD/LINE/INSTRUCTION 50%, BRANCH +40%, PROJECT baseline and UNSTABLE criticality. Reports from partially failed +test runs are useful diagnostics, not a passing quality gate. + +## Contract and manual verification boundary + +See the packer fixture [provenance and coverage](../../prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md). +The automated suite checks producer bytes and metadata against independent +expectations. Runtime gameplay remains manual with existing games, not a local +or CI automated test. Record manual outcomes only after execution. + +Local Gradle checks and Groovy parsing cannot certify controller plugin behavior. +A Jenkins run is needed to observe actual report publication and coverage checks; +report any unavailable controller validation explicitly. + +Jenkins behavior references: [post conditions](https://www.jenkins.io/doc/book/pipeline/syntax/#post) +and [catchError](https://www.jenkins.io/doc/pipeline/steps/workflow-basic-steps/#catcherror-catch-error-and-set-build-result-to-failure). diff --git a/prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetContractTest.java b/prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetContractTest.java new file mode 100644 index 00000000..4c8e4340 --- /dev/null +++ b/prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetContractTest.java @@ -0,0 +1,219 @@ +package p.packer.services; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ArrayNode; +import com.fasterxml.jackson.databind.node.ObjectNode; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import p.packer.messages.*; +import p.packer.repositories.*; + +import javax.imageio.ImageIO; +import java.awt.image.BufferedImage; +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.Arrays; +import java.util.HexFormat; +import java.util.List; +import java.util.Objects; + +import static org.junit.jupiter.api.Assertions.*; + +/** Producer contract checks only: no runtime executable or runtime decoder. */ +final class PackerAssetContractTest { + private static final ObjectMapper JSON = new ObjectMapper(); + private static final int[] COLORS = {0x123456ff, 0xabcdef80, 0x34567800, 0x876543ff}; + @TempDir Path projectRoot; + + @ParameterizedTest + @CsvSource({"8,1", "16,3", "32,64"}) + void glyphPayloadMatchesIndependentNibblesAndRgba(int tileSize, int paletteCount) throws Exception { + glyph(7, tileSize, paletteCount, true); + registry(7); + final Envelope packed = pack(); + final JsonNode entry = packed.header().path("asset_table").get(0); + assertEquals("GLYPH", entry.path("bank_type").asText()); + assertEquals("NONE", entry.path("codec").asText()); + assertEquals(tileSize, entry.path("metadata").path("tile_size").asInt()); + assertEquals(256, entry.path("metadata").path("width").asInt()); + assertEquals(256, entry.path("metadata").path("height").asInt()); + assertEquals(paletteCount, entry.path("metadata").path("palette_count").asInt()); + assertEquals(32768 + paletteCount * 64, entry.path("size").asInt()); + assertEquals(65536 + paletteCount * 64, entry.path("decoded_size").asInt()); + assertArrayEquals(expectedGlyph(tileSize, paletteCount), packed.slice(entry)); + } + + @Test + void embeddedHeaderAddressesMultipleAssetsAndPreloadsByBankIdentity() throws Exception { + glyph(7, 8, 1, true); + glyph(33, 8, 1, false); + glyph(16909060, 8, 1, true); + scene(99); + // Deliberately unsorted registry; asset identity must not become list index or slot. + registry(16909060, 99, 33, 7); + final Envelope packed = pack(); + final JsonNode entries = packed.header().path("asset_table"); + assertEquals(List.of(7, 33, 99, 16909060), + java.util.stream.StreamSupport.stream(entries.spliterator(), false) + .map(e -> e.path("asset_id").asInt()).toList()); + assertEquals(JSON.readTree(""" + [{"asset_id":7,"slot":0},{"asset_id":99,"slot":0},{"asset_id":16909060,"slot":1}] + """), packed.header().path("preload")); + int end = 0; + for (JsonNode entry : entries) { + assertEquals(end, entry.path("offset").asInt(), "offset is payload-relative and contiguous"); + assertEquals("NONE", entry.path("codec").asText()); + if (entry.path("asset_id").asInt() == 99) { + assertEquals("SCENE", entry.path("bank_type").asText()); + assertEquals(1, entry.path("metadata").path("version").asInt()); + assertEquals(4, entry.path("metadata").path("layer_count").asInt()); + assertEquals(96, entry.path("decoded_size").asInt()); // 4 * (16 overhead + 8 tile) + assertArrayEquals(hex("scene-v1.hex"), packed.slice(entry)); + } else { + assertArrayEquals(expectedGlyph(8, 1), packed.slice(entry)); + } + end += entry.path("size").asInt(); + } + assertEquals(packed.bytes().length, packed.payloadOffset() + end, "no unaddressed/trailing payload"); + } + + @Test + void invalidPaletteCannotPublishAnAssetArtifact() throws Exception { + glyph(7, 8, 1, true); + registry(7); + Path manifestPath = asset(7).resolve("asset.json"); + ObjectNode manifest = (ObjectNode) JSON.readTree(manifestPath.toFile()); + ((ObjectNode) manifest.path("output").path("pipeline").path("palettes").get(0)).put("index", 64); + JSON.writeValue(manifestPath.toFile(), manifest); + final var result = service().packWorkspace(new PackWorkspaceRequest(project())); + assertEquals(PackerOperationStatus.PARTIAL, result.status()); + assertTrue(result.result().emittedArtifacts().isEmpty()); + assertFalse(Files.exists(projectRoot.resolve("build/assets.pa"))); + } + + private Envelope pack() throws Exception { + final var result = service().packWorkspace(new PackWorkspaceRequest(project())); + assertEquals(PackerOperationStatus.SUCCESS, result.status(), result.toString()); + final byte[] bytes = Files.readAllBytes(projectRoot.resolve("build/assets.pa")); + final ByteBuffer prelude = ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN); + assertArrayEquals(new byte[]{'A', 'S', 'P', 'A'}, Arrays.copyOf(bytes, 4)); + assertEquals(1, prelude.getInt(4)); + int headerLength = prelude.getInt(8); + assertTrue(headerLength > 0); + assertEquals(32L + headerLength, prelude.getLong(12)); + assertArrayEquals(new byte[12], Arrays.copyOfRange(bytes, 20, 32)); + int payloadOffset = Math.toIntExact(prelude.getLong(12)); + JsonNode header = JSON.readTree(Arrays.copyOfRange(bytes, 32, payloadOffset)); + assertEquals(JSON.readTree(projectRoot.resolve("build/asset_table.json").toFile()), header.path("asset_table")); + assertEquals(JSON.readTree(projectRoot.resolve("build/preload.json").toFile()), header.path("preload")); + return new Envelope(bytes, header, payloadOffset); + } + + private record Envelope(byte[] bytes, JsonNode header, int payloadOffset) { + byte[] slice(JsonNode entry) { + int start = payloadOffset + entry.path("offset").asInt(); + int end = start + entry.path("size").asInt(); + assertTrue(start >= payloadOffset && end <= bytes.length); + return Arrays.copyOfRange(bytes, start, end); + } + } + + private byte[] expectedGlyph(int tileSize, int palettes) throws Exception { + byte[] expected = new byte[32768 + palettes * 64]; + // Fixed 256-pixel sheet: repeat the independently authored 8-pixel row in the first tile. + byte[] row = hex("glyph-row.hex"); + for (int y = 0; y < tileSize; y++) { + for (int x = 0; x < tileSize / 8; x++) { + System.arraycopy(row, 0, expected, y * 128 + x * 4, row.length); + } + } + byte[] colors = hex("glyph-colors.hex"); + for (int palette = 0; palette < palettes; palette++) { + System.arraycopy(colors, 0, expected, 32768 + palette * 64, colors.length); + } + return expected; + } + + private void glyph(int id, int tileSize, int palettes, boolean preload) throws Exception { + ObjectNode manifest = manifest(id, "glyph_bank", "GLYPH/indexed_v1", preload); + ObjectNode output = (ObjectNode) manifest.path("output"); + output.putObject("metadata").put("tile_size", tileSize + "x" + tileSize); + ArrayNode table = output.putObject("pipeline").putArray("palettes"); + for (int p = 0; p < palettes; p++) { + ObjectNode palette = table.addObject().put("index", p); + ArrayNode colors = palette.putObject("palette").putArray("rgba8888"); + for (int color : COLORS) colors.add(color); + } + manifest.putArray("artifacts").addObject().put("file", "tile.png").put("index", 0); + JSON.writeValue(asset(id).resolve("asset.json").toFile(), manifest); + BufferedImage image = new BufferedImage(tileSize, tileSize, BufferedImage.TYPE_INT_ARGB); + for (int y = 0; y < tileSize; y++) { + for (int x = 0; x < tileSize; x++) { + int rgba = COLORS[x % 4]; + image.setRGB(x, y, (rgba >>> 8) | (rgba << 24)); + } + } + assertTrue(ImageIO.write(image, "png", asset(id).resolve("tile.png").toFile())); + } + + private void scene(int id) throws Exception { + JSON.writeValue(asset(id).resolve("asset.json").toFile(), manifest(id, "scene_bank", "SCENE/tilemap_v1", true)); + ObjectNode request = JSON.createObjectNode().put("schema_version", 1).put("format", "SCENE/tilemap_v1").put("version", 1); + ArrayNode layers = request.putArray("layers"); + for (int i = 0; i < 4; i++) { + ObjectNode layer = layers.addObject().put("active", true).put("glyph_asset_id", 16909060) + .put("tile_size", 8).put("parallax_factor_x", 1.0).put("parallax_factor_y", 0.5) + .put("width", 1).put("height", 1); + layer.putArray("tiles").addObject().put("active", true).put("glyph_id", i) + .put("palette_id", 0).put("flip_x", (i & 1) != 0).put("flip_y", (i & 2) != 0); + } + JSON.writeValue(asset(id).resolve("scene-bank.pack-request.json").toFile(), request); + } + + private ObjectNode manifest(int id, String type, String format, boolean preload) throws Exception { + Files.createDirectories(asset(id)); + ObjectNode manifest = JSON.createObjectNode().put("schema_version", 1).put("asset_uuid", "contract-" + id) + .put("name", "asset_" + id).put("type", type); + manifest.putObject("output").put("format", format).put("codec", "NONE"); + manifest.putObject("preload").put("enabled", preload); + return manifest; + } + + private void registry(int... ids) throws Exception { + Path path = projectRoot.resolve("assets/.prometeu/index.json"); + Files.createDirectories(path.getParent()); + ObjectNode registry = JSON.createObjectNode().put("schema_version", 1).put("next_asset_id", 16909061); + ArrayNode assets = registry.putArray("assets"); + for (int id : ids) assets.addObject().put("asset_id", id).put("asset_uuid", "contract-" + id) + .put("root", "asset-" + id).put("included_in_build", true); + JSON.writeValue(path.toFile(), registry); + } + + private Path asset(int id) { return projectRoot.resolve("assets/asset-" + id); } + private PackerProjectContext project() { return new PackerProjectContext("contract", projectRoot); } + private byte[] hex(String name) throws Exception { + try (var input = Objects.requireNonNull(getClass().getResourceAsStream("/fixtures/contracts/" + name))) { + return HexFormat.of().parseHex(new String(input.readAllBytes(), StandardCharsets.UTF_8).replaceAll("\\s", "")); + } + } + + private FileSystemPackerWorkspaceService service() { + var foundation = new PackerWorkspaceFoundation(JSON); + var parser = new PackerAssetDeclarationParser(JSON); + var cache = new FileSystemPackerCacheRepository(JSON); + var materializer = new PackerRuntimeAssetMaterializer(new PackerAssetWalker(JSON)); + var registry = new PackerRuntimeRegistry(new PackerRuntimeLoader(foundation, parser, cache, materializer)); + var resolver = new PackerAssetReferenceResolver(foundation.lookup()); + return new FileSystemPackerWorkspaceService(JSON, foundation, + new PackerAssetDetailsService(registry, resolver), + new PackerAssetActionReadService(registry, resolver, foundation.lookup()), + new PackerRuntimePatchService(parser, materializer), registry, cache, + new PackerProjectWriteCoordinator(), event -> {}); + } +} diff --git a/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md new file mode 100644 index 00000000..d1c51ee8 --- /dev/null +++ b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md @@ -0,0 +1,59 @@ +# Packer binary contract fixtures + +These expectations are authored from the published wire contract, independently +of the Java writer. They are not captured from packer output. Tests call the real +`packWorkspace` service and read the embedded header and payload of `assets.pa`; +JSON sidecars alone are not the oracle. + +Reference snapshot: runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`: + +- `docs/specs/runtime/15-asset-management.md`, sections 3–4 and 9; +- `crates/console/prometeu-hal/src/asset.rs`, scene layout constants; +- `crates/console/prometeu-drivers/src/asset/decode.rs`, nibble and channel order. + +The Studio producer's fixed 256×256 sheet and asset envelope are documented in +`docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`. +No runtime checkout, executable or decoder is needed to execute these tests. + +## Fixture interpretation + +- `glyph-row.hex`: eight indexed pixels `0,1,2,3,0,1,2,3`, high nibble first. + The test repeats this row within the first 8/16/32-pixel tile and leaves the + rest of the 256×256 sheet at index zero. +- `glyph-colors.hex`: four independent RGBA colors, including opaque index zero, + partial alpha at index one, transparent index two and distinct channel values. + Each palette has these four colors followed by twelve zero entries. Tests + exercise 1, 3 and 64 palettes and compare the entire serialized bank. +- `scene-v1.hex`: a 12-byte SCNE/version-1/four-layer header followed by four + 32-byte layer headers and one four-byte tile per layer. All layers are active, + use glyph AssetId `0x01020304` (16909060, not its preload slot 1), tile size 8, + parallax (1.0, 0.5), width/height/count 1 and zero reserved fields. Tile flags + are 1/3/5/7, exercising both flip bits; palette is zero and glyph IDs are + 0/1/2/3. Serialized size is 156; decoded size is 4 × (16 + 8) = 96. + +The mixed-asset test includes an asset with preload disabled and two GLYPH +preloads in slots 0/1 plus a SCENE preload in slot 0. It checks payload-relative +nonzero offsets, stable IDs, no payload gaps/trailing bytes, and equality between +the embedded header and exported sidecars. The invalid-palette case verifies +that palette index 64 cannot publish a new `assets.pa`. + +Existing `FileSystemPackerWorkspaceServiceTest` coverage remains responsible for +basic emission, sparse palettes, material remapping, frozen snapshots and +selected SCENE fields. These fixtures complement those tests at the complete +artifact boundary rather than porting the runtime's decoder corpus. + +## Execution and limits + +```sh +./gradlew :prometeu-packer:prometeu-packer-v1:test --tests '*PackerAssetContractTest' +``` + +The suite also runs under ordinary `./gradlew test`. ImageIO uses in-memory +images and temporary files; no display is needed. Fixtures never launch a +runtime, skip for missing runtime, or fall back to a simulated runtime. + +Passing these tests demonstrates producer contract coverage, not runtime +loading/rendering. Integrated verification is manual using existing games. +Record the game, Studio/runtime revisions, actions and observed result when +that verification is actually performed; do not infer a gameplay pass from +these byte comparisons. diff --git a/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/glyph-colors.hex b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/glyph-colors.hex new file mode 100644 index 00000000..f08433d2 --- /dev/null +++ b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/glyph-colors.hex @@ -0,0 +1 @@ +123456ff abcdef80 34567800 876543ff diff --git a/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/glyph-row.hex b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/glyph-row.hex new file mode 100644 index 00000000..b91169e7 --- /dev/null +++ b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/glyph-row.hex @@ -0,0 +1 @@ +01230123 diff --git a/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/scene-v1.hex b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/scene-v1.hex new file mode 100644 index 00000000..f5a81e5b --- /dev/null +++ b/prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/scene-v1.hex @@ -0,0 +1,9 @@ +53434e45 0100 0400 00000000 +01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000 +01 00 0000 +01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000 +03 00 0100 +01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000 +05 00 0200 +01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000 +07 00 0300