[Tooling] Auto Storage Compat Kit for semi-automated addon integration

[swear01]

Goal

Build a reusable Auto Storage Compat Kit that reduces the repeated investigation and scaffolding work needed to add deterministic cross-mod support, while preserving Auto Storage's fail-closed, server-authoritative transaction contract.

The tool is for both repository-owned bundled modules and independent third-party addon projects. It automates evidence collection, boilerplate, and verification; it must never infer unsafe runtime semantics or silently downgrade an incomplete integration.

Design principles

• Development-time automation only: no runtime jar scanning, reflection fallback, recipe-name guessing, or EMI/JEI-driven crafting logic.
• Facts may be extracted automatically; consumption, catalyst, remainder, output, work, and determinism semantics require an explicit reviewed contract.
• Unknown or ambiguous fields remain needs_decision and block generation/verification.
• Target versions and SHA-256 values are reproducible audit/CI evidence, not exact player dependency pins or a multi-version support promise.
• Generated modules must use the public AutoStorageAddon.register(...) SDK introduced by [API/Architecture] Modular compatibility SDK and conditional built-in modules #32.
• Python standard library plus JDK tools first; no new Auto Storage runtime dependency and no Gradle plugin until demonstrated necessary.

Proposed workflow

1. scan

compat-kit scan --jar <target.jar> [--source <checkout>] --output <audit.json>

Produce a compact, deterministic compat-audit.json containing:

• mod ID, declared version, source/release reference, and jar SHA-256;
• recipe types, serializers, concrete recipe classes, registry IDs, and public signatures;
• station/item candidates and public item/fluid/energy/chemical/addon resource APIs;
• sample recipe shape evidence where static data is available;
• explicit risk flags for chance outputs, world/entity mutation, multiblocks, live external-machine state, unbounded/dynamic output, missing simulation, and generic Recipe#getIngredients() surfaces;
• file/class/method evidence references without embedding entire upstream source trees.

Implementation baseline: Python zipfile/json/hashlib plus JDK javap -public/-c/-p.

2. decide

Convert the audit into a reviewed compat-contract.json that records, per accepted recipe family:

• exact recipe class and RecipeType;
• consumed inputs, catalysts, tools/durability, remainders, and complete outputs;
• typed resource keys and units;
• logical station descriptor and exact variants/rational rates;
• station-work and energy/resource costs;
• deterministic bounds and rejected families with reasons.

The CLI should generate next-actions.md containing only unresolved semantic decisions. This is the primary token-reduction boundary: agents and contributors read the compact audit, contract, and version delta instead of repeatedly rereading a complete upstream repository.

3. scaffold

compat-kit scaffold --bundled <contract.json>
compat-kit scaffold --addon <contract.json> --output <directory>

Bundled mode generates or updates:

• src/compat/<mod-id>/compat-module.json;
• isolated module entrypoint/package and DeferredRegister skeletons;
• present-mod fixture and behavior-test skeletons;
• support-matrix/documentation stubs;
• representative CI dependency/property wiring owned by the module descriptor.

External mode generates an ordinary NeoForge addon project with:

• Auto Storage API dependency and dependency metadata;
• one-call AutoStorageAddon.register(...) entrypoint;
• the same public registry contracts;
• a minimal GameTest/CI template;
• no access to Auto Storage implementation classes.

Incomplete generated behavior must remain an explicit RED test or generation error, never a compiling empty integration.

4. verify

compat-kit verify <contract.json> [--bundled | --addon <directory>]

Generate/run a machine-readable verification report covering:

• absent target mod: no compatibility entrypoint classloading;
• present target mod: load exactly once and execute real recipe assertions;
• shortage, destination capacity, checked overflow, stale recipe holder, catalyst/tool/remainder handling, multi-output merging, and mixed-resource atomic rollback;
• dedicated-server client-class isolation;
• API-only compilation and forbidden implementation/optional-mod links;
• all-mod coexistence matrix registration/classpath conflicts.

5. diff

compat-kit diff <old-audit.json> <new-target.jar>

Cache scans by target jar SHA-256 and report only changed classes, signatures, recipe types, registry IDs, and contract-affected evidence. Do not rescan/re-explain unchanged upstream surfaces.

6. publish

Publish a versioned auto-storage-compat-kit.zip containing:

• CLI;
• JSON Schemas;
• bundled and external templates;
• external addon example;
• a reusable GitHub Actions workflow/example;
• concise developer documentation.

Suggested repository layout

tools/compat-kit/
  compat_kit.py
  schema/
  templates/
  tests/
compat/audits/<mod-id>/<version>.json
compat/contracts/<mod-id>.json

Generated transient caches stay under build/compat-kit/cache/<sha256>/ and are not committed.

Delivery phases

Phase 1 — audit contract

• Define versioned audit/contract/report JSON Schemas.
• Add scan, decide, diff, SHA cache, and golden fixture tests.
• Reject unknown schema keys and incomplete accepted families.

Phase 2 — scaffolding

• Generate bundled modules using module-owned compat-module.json.
• Generate an independent external NeoForge addon project.
• Add deterministic regeneration/drift tests.

Phase 3 — verification and CI

• Generate behavior-test skeletons and one machine-readable report.
• Integrate API isolation, absent/present module, and optional coexistence checks.
• Keep representative single-version fixtures without player-facing exact pins.

Phase 4 — external distribution

• Release Compat Kit archive and schemas.
• Add developer-only Wiki documentation without adding it to the player manual navigation.
• Provide a reusable CI example for addon authors.

First dogfood target

Use the AE2 Inscriber slice in #33:

1. scan the audited AE2 artifact/source;
2. review and commit the explicit Inscriber contract;
3. scaffold the bundled AE2 module and RED fixture;
4. complete the implementation through the public [API/Architecture] Modular compatibility SDK and conditional built-in modules #32 SDK;
5. rerun scan/diff against a second representative AE2 artifact only to validate delta reporting—not as a compatibility promise or multi-version matrix.

Acceptance criteria

• Repeating a scan of the same SHA produces byte-identical audit output without network access.
• A target-version update produces a compact delta and only unresolved decisions, not a full-source report.
• Ambiguous/random/world-state behavior cannot produce a green module without an explicit contract decision.
• Bundled output is discovered by the existing module-owned descriptor build and requires no central compatibility switch edit.
• External output compiles against only the public API artifact and NeoForge/Minecraft dependencies.
• Generated verification covers transaction atomicity and absent/present classloading boundaries.
• CLI, schemas, templates, and reports have regression/golden tests.
• The player runtime jar gains no scanner, scripting engine, reflection fallback, or new runtime dependency.
• Documentation clearly distinguishes audit fixture versions from player dependency ranges.

Dependencies

• [API/Architecture] Modular compatibility SDK and conditional built-in modules #32 — public modular compatibility SDK and module-owned metadata
• [Compatibility] Audit and expand deterministic support for ATM10 1.21.1 #33 — ATM10 compatibility audit and AE2 Inscriber dogfood target