Implement first useful verified automation module: ItemSorterSlice

[madawei2699]

Parent

Follow-up / sub-issue for #53.

Context

Basic redstone block support is useful, but it risks stopping at toy examples such as lamps, clocks, and simple piston doors. Those are good engineering smoke tests, but they are not enough to validate the real product value of CraftDAG + MinePilot for redstone and automation workflows.

The first redstone milestone should cross the line from "can place redstone blocks" to "can generate a useful Minecraft automation module that players would otherwise struggle to build and debug."

A single item sorter slice is a good first proof-of-value because it forces the engine to handle the important hard parts:

• hopper facing
• comparator facing
• redstone torch placement
• repeater / dust routing
• output container connection
• optional filter hopper inventory NBT
• module initialization instructions
• repeated-slice future extensibility
• troubleshooting guidance

Goal

Implement a first useful verified automation module:

ItemSorterSlice

The module should be exportable as a vanilla Java Edition-compatible schematic structure and should come with static/module validation, material output, layer output, and clear initialization/troubleshooting notes.

Why this matters

This issue is the value checkpoint for the redstone direction.

If CraftDAG can only generate simple redstone toys, the direction has limited product value. If it can generate a correct, explainable, configurable item sorter slice, the path to more valuable modules becomes credible:

• ItemSorterArray
• StorageWall
• AutoSmelter
• DropperElevator
• farm-cell arrays
• base automation systems

Suggested staged scope

Stage 0: structure-only slice

Create a structure-only ItemSorterSlice plan/module that places the correct vanilla blocks and directions, but does not yet require filter-item NBT support.

It should provide manual initialization instructions, for example:

Place 41 target items in the filter hopper and one filler item in each remaining filter slot.
Use renamed filler items so regular items do not enter filler slots.

This stage is acceptable only if the UI/docs clearly mark the module as structure-only / manual-initialization required.

Stage 1: filter hopper NBT support

Add or use block entity support so the module can initialize the filter hopper inventory.

The module should be able to express something equivalent to:

slot 0: target item, count 41
slots 1-4: filler item, count 1 each

If this requires a broader VoxelPlan / schematic exporter extension, scope it deliberately and keep it Java Edition-oriented.

Stage 2: small array probe

After a single slice works, add a small array probe such as:

ItemSorterArray count=4

This validates spacing, repeated module placement, input line continuity, output containers, and material/layer output.

A full 16/32/64-slot storage wall is future work.

Proposed authoring shape

The exact schema can be designed during implementation, but the module should be describable at a high level like:

{
  "type": "RedstoneModule",
  "module": "ItemSorterSlice",
  "versionTarget": "java_1_21",
  "placement": {
    "anchor": { "x": 0, "y": 0, "z": 0 },
    "facing": "south"
  },
  "options": {
    "filterItem": "minecraft:cobblestone",
    "fillerItem": "minecraft:stick",
    "initializeFilter": false
  }
}

If RedstoneModule is not ready yet, a temporary internal fixture or helper is acceptable, but the design should not rely on LLM-authored raw redstone coordinates.

Validation requirements

Static validation

Validate at least:

• all block states are legal
• all directional blocks have valid facing
• the module stays within declared bounds
• hopper/comparator/repeater orientation is consistent with the module facing
• the output container exists
• no required critical blocks are missing

Module-specific validation

The module validator should check critical structure invariants, such as:

• filter hopper exists
• comparator reads from the filter hopper
• redstone torch lock path exists
• output hopper/container path exists
• input line and overflow path are defined or documented

Block entity validation, if Stage 1 is implemented

Validate:

• filter hopper inventory exists
• target item is valid
• filler item is valid
• counts are correct
• unsupported inventory initialization clearly fails or downgrades to manual-init mode

Output requirements

The generated artifact should produce:

• VoxelPlan / schematic export
• material list
• layer guide
• module metadata
• initialization steps
• common mistakes / troubleshooting notes
• Java Edition version target
• known limitations

MinePilot expectation

MinePilot does not need to implement this in the same PR, but the module should be designed so MinePilot can later show:

• Redstone / Automation category
• 3D preview
• critical block highlights
• working principle
• initialization steps
• common mistakes
• material list
• layer guide
• schematic export

Non-goals

• Do not build a full browser redstone simulator.
• Do not attempt arbitrary redstone circuit synthesis.
• Do not support Bedrock behavior.
• Do not generate raw WorldEdit or bot commands.
• Do not require a full 16/32/64-slot storage wall in the first implementation.
• Do not claim the module is fully automatic unless block entity initialization and smoke-test evidence support that claim.

Acceptance criteria

• A single ItemSorterSlice module/fixture can be generated deterministically.
• The module exports to schematic-compatible VoxelPlan output.
• Static validation checks critical redstone directions and bounds.
• Materials and layers are generated.
• Initialization/troubleshooting metadata is available.
• If filter hopper NBT is not implemented, the module is clearly marked as manual-initialization required.
• If filter hopper NBT is implemented, tests verify expected inventory data.
• At least one fixture test covers the module.
• A follow-up path to ItemSorterArray count=4 is documented.

Future follow-ups

• ItemSorterArray
• StorageWall
• AutoSmelterMini
• block entity support generalization
• MinePilot redstone/automation gallery support
• real Minecraft / WorldEdit smoke-test checklist