v0.1.1-alpha - First Release: Shape B Init-Zeroing & Four-Shape Latent Protocol

ComfyUI-DazzleKSampler v0.1.1-alpha

DazzleKSampler is a ComfyUI custom node providing enhanced KSampler nodes with shaped-noise passthrough and the four-shape latent-dict protocol. It is a port of RES4LYF's sampling engine (AGPL-3.0) with DazzleNodes-specific behavior layered on top.

This is the first real pre-alpha release of the project. Earlier internal commits (v0.1.0-alpha) ported the RES4LYF engine; v0.1.1-alpha is the first version published as a pre-release for collaborators and adventurous early users. Treat the project as genuinely alpha — well-understood scope, one real fix, one preview node, an honest roadmap, and a lot of open issues.

Headline

The seed=-2 latent-as-noise pipeline now works correctly for Shape B latents. When an upstream latent had use_as_noise=True but no separate noise key (Shape B in the four-shape protocol), the same tensor was previously passed to the underlying ComfyUI sampler in BOTH the noise role AND the init-image role:

initial_x = z_norm(samples) * sigmas[0] + samples
          = z_norm(L) * sigma_max + L          # bug: L appears twice

That double-anchor locked composition to the latent's structure regardless of upstream noise shaping (fill_type, blend_strength). Symptom: changing fill_type from DazNoise:Brown to DazNoise:Plasma to anything else produced near-identical compositions, while changing the seed away from -2 produced dramatic variation.

The fix zeroes the init slot when latent-as-noise mode activates without a separate noise tensor:

initial_x = z_norm(samples) * sigmas[0] + 0
          = z_norm(L) * sigma_max

Shape C (img2img + img2noise, with separate noise key) is unchanged — img2img-with-shaped-noise semantics are preserved. Shapes A and D (no use_as_noise flag) fall through to deterministic seed-driven noise generation, also unchanged.

What's New

Shape B init-zeroing fix (fix: Zero init slot in Shape B latent-as-noise dispatch)

The dispatch is centralized in a new pure helper module — py/beta/_latent_noise_protocol.py — so the contract is testable and the four shapes are documented in one place:

def resolve_latent_as_noise(latent, x, noise_seed):
    # Returns (noise_or_None, x_or_zeros, "shape_b" | "shape_c" | "not_applied")

samplers.py now calls the helper at the dispatch site instead of the inline branch. Console messages distinguish Shape B (init zeroed) from Shape C (noise key) for runtime verification.

Four-shape latent-dict protocol (formalized)

Shape	Dict	Produced by SmartResCalc when
A — Pure init	{ "samples": vae_encoded }	image_purpose = img2img
B — Pure noise	{ "samples": shaped_noise, "use_as_noise": True }	dimensions only / img2noise / image + noise with non-trivial fill_type
C — Layered	{ "samples": encoded, "noise": shaped_noise, "use_as_noise": True }	img2img + img2noise
D — Empty	{ "samples": zeros }	fill_type ∈ {black, white, custom_color} or stock EmptyLatentImage

Documented in full in docs/wiki/Noise-Passthrough.md, which has been rewritten for this release with the four-shape table, the math behind the fix, dispatch code walkthrough, caveats, and a troubleshooting section.

Tests

13 automated cases in tests/test_latent_noise_protocol.py cover every shape × seed combination, including a regression guard for Shape C and a deterministic-seed-noise guard for Shape D (the fill_type=black case). A human test checklist at tests/checklists/v0.1.1-alpha__Fix__seed-minus-2-dual-role-bug.md covers what mocks cannot — real ComfyUI sampling against a live model with SmartResCalc upstream.

Nodes Shipped

These come from the v0.1.0-alpha port and are all available in this release. Categorization currently shows under RES4LYF/samplers in the ComfyUI menu (Issue #6 will fix this to DazzleNodes/Sampling).

• DazzleKSampler — all-in-one (model + conditioning + latent → latent)
• DazzleKSampler_Advanced — SAMPLER output for use with SamplerCustomAdvanced
• DazzleKSampler_Chain — continues from previous run's state
• DazzleSharkSampler — split orchestrator, accepts a separate SAMPLER object
• DazzleClownSampler / DazzleBongSampler — ported from RES4LYF

Preview / Unreleased

Dazzle TauSampler is in the repo and listed under [Unreleased] in the CHANGELOG. It implements tau complement sampling (based on the Tau Operator from D. Darcy's Scarcity Framework) with variants tau/res_2m, tau/res_2s, tau/dpmpp_2m, tau/dpmpp_2m_sde, tau/dpmpp_2s, tau/dpmpp_3m and three modes (hard / soft / cosine). tau_strength=0 is bit-identical to standard samplers.

Caveat (verbatim from CHANGELOG): "v1 implementation is a simplified complement (x_0 - x_next). Future versions will implement proper structure/noise separation in the complement via the resolution function R." The tau4 spectral per-bin variant exists in the codebase but is not yet wired to a widget. TauSampler is available for early experimentation; do not treat it as stable.

Known Limitations and Roadmap

Open issues at release time:

• #10 — seed=-2 is still a magic number. Smart latent detection planned: DazzleKSampler will inspect the dict shape and infer passthrough intent without the -2 convention. Backward-compatible (-2 will keep working).
• #9 — No euler_ancestral sampler. Proposed: linear/euler_ancestral preset with baked eta=1.0, noise_mode="hard", s_noise=1.0.
• #6 — Nodes display under RES4LYF/samplers instead of DazzleNodes/Sampling. Includes replacing print() with logger.debug throughout.
• #5 — Monkey-patches present at import time (comfy.samplers.calculate_sigmas, comfy.model_sampling.time_snr_shift). The time_snr_shift patch is deprecated even in upstream RES4LYF.
• #4 — py/beta/samplers.py is a 2,465-line monolith with 9 classes. Refactor into py/nodes/ and py/sampling/ proposed but not started.
• #3 — DazzleCommand seed orchestration integration not done. README marks it "planned." No dazzle_signal input yet.

Additional gap: ClownSampler and BongSampler are present but not yet documented in the wiki.

Installation

ComfyUI custom node — install via the ComfyUI Manager or clone into your custom_nodes/ directory:

cd ComfyUI/custom_nodes
git clone https://github.com/DazzleNodes/ComfyUI-DazzleKSampler.git

Restart ComfyUI. Nodes will appear under RES4LYF/samplers (current — see #6).

Setting Up Noise Passthrough

1. SmartResCalc — pick an image_purpose that produces a Shape B or Shape C latent:
   • dimensions only + non-trivial fill_type (e.g., DazNoise:Brown) → Shape B
   • img2noise (with image attached) → Shape B
   • image + noise → Shape B
   • img2img + img2noise → Shape C
2. DazzleKSampler — set noise_seed = -2 to activate passthrough.
3. Connect SmartResCalc's latent output to DazzleKSampler's latent_image input.

fill_type ∈ {black, white, custom_color} and stock EmptyLatentImage produce Shape D and fall through to seed-driven noise — a normal positive seed value is required for those.

Version History

Version	Key Change
v0.1.1-alpha	Current — Shape B init-zeroing fix; four-shape protocol formalized; first published release
v0.1.0-alpha (unreleased)	Initial port of RES4LYF ClownsharKSampler under DazzleNodes namespace

Platform Support

Platform	Status
Windows (ComfyUI portable / manual)	Tested (development platform)
Linux	Expected to work
macOS	Expected to work

Requirements

• ComfyUI (any recent version)
• Python ≥ 3.10
• PyTorch (whatever ComfyUI is running)
• Optional: ComfyUI-Smart-Resolution-Calc for the four-shape protocol upstream

Credits / Upstream / License

The core sampling engine — RK solver mathematics, noise generation, scheduler infrastructure, and all six base nodes — is a port of RES4LYF by ClownsharkBatwing (ClownsharkBeta). The RK solver, noise generators, and scheduler infrastructure are derived from that work.

License: AGPL-3.0 with commercial restriction. From LICENSE:

This restriction is inherited from upstream RES4LYF and carries forward in this port. DazzleNodes-specific additions (Shape B init-zeroing, the four-shape protocol module, TauSampler) are by D. Darcy and are also under AGPL-3.0 with the same commercial restriction.

What This Release Is Not

This release does NOT:

• Replace the seed=-2 magic value with an explicit widget (planned — see #10)
• Provide euler_ancestral (#9)
• Categorize nodes under DazzleNodes/Sampling (#6)
• Remove monkey-patches (#5)
• Decompose the monolithic samplers.py (#4)
• Integrate with DazzleCommand (#3)
• Promote TauSampler out of preview status

If any of those are blockers for your workflow, watch the linked issues. Otherwise, the headline use case — SmartResCalc → DazzleKSampler with seed=-2 for shaped-noise generation — is now correct for the first time, and the four-shape protocol gives a stable contract to build on.