Freeze local image capability and add machine compatibility gating

[xueyang-dev]

Summary

• add a versioned, SHA-256-pinned local-image compatibility contract binding the existing ComfyUI Runtime, SD 1.5 Model Package, and official-core-node Workflow Pack
• probe OS/architecture, macOS version, Metal/MPS, total memory, free disk, real-validation status, and all fixed manifest identities
• keep runtime_ready, model_compatible, model_installed, workflow_ready, and generation_ready as separate backend facts
• fail closed on unknown or incompatible machines and recheck compatibility before Runtime/model install or repair, Runtime start, generation preflight, and post-generation publication
• preserve backend-owned confirmation and ownership checks; stop and owned uninstall remain available for recovery
• present the capability as “本地基础生图” in Provider Hub with the four compatibility states, structured reasons, action gating, five readiness facts, and an explicit recheck action
• hide implementation-level model/workflow and sampling details from the teacher surface
• document the frozen v1 production identity, support matrix, disk thresholds, reason codes, cache invalidation, review boundary, and non-goals

Why

The Phase 2C generation pipeline had a validated fixed Runtime/model/workflow identity, but machine suitability was not yet a first-class backend gate. Runtime installation alone also must not imply that the fixed image capability can run. This change makes machine compatibility explicit, versioned, fail-closed, and independently revalidated at every operation boundary.

Final boundary audit

The final audit found and fixed four P1 boundary gaps without changing capability behavior:

• the live pinned /system_stats response must report devices[0].type == "mps"; missing, ambiguous, or CPU primary-device state is a Runtime identity failure
• the compatibility cache is now bound to the current bytes of the compatibility contract plus all three fixed manifests and fails closed if those inputs change during probing
• Runtime/model publication, Runtime process spawn, project image/provenance writes, and Asset Manifest publication each repeat the current backend compatibility/identity check at their final boundary
• Provider Hub recomposes generation_ready with the current machine conclusion, so a stale prior joint-health result cannot override unknown or incompatible; stop, force-stop, and owned uninstall remain available

Accepted P2 limits are recorded in the freeze document: catalog-only volatile facts may be up to 300 seconds old, disk evidence uses OS-visible free bytes rather than APFS purgeable/quota predictions, and recovery still requires intact fixed manifests plus ownership evidence. None weakens a mutation or publication gate.

Current support matrix

The sole enabled row is macOS 14+ on Apple Silicon arm64 with verified Metal/MPS, at least 16 GiB memory, the required action-specific disk reserve, real lifecycle evidence, and matching fixed identities. It reports compatible_limited because support remains experimental. Windows, Linux, non-arm64 macOS, and known insufficient hardware are incompatible; missing facts report unknown and fail closed. There is no CPU fallback or substitute model.

A real detector run on the development host reported macOS 26.5.2 / arm64, Metal/MPS available, 16 GiB memory, more than the 10 GiB full-install reserve, and all three manifest identities verified. Result: compatible_limited with only experimental_support. This check did not install or execute a Runtime or model and did not produce an image.

Validation

• npm run test:api — 674 passed, 3 skipped (real model/Runtime opt-in tests intentionally not enabled)
• npm --prefix apps/web run build — TypeScript noEmit and Vite production build passed
• npm --prefix apps/web run test:state — passed
• npm run test:e2e — 15 passed
• Ruff — full default rules for the new compatibility module/tests; F/E9 changed-file gate for existing Python modules, passed
• git diff --check origin/main...HEAD — passed
• working tree clean

Frozen boundary

This PR does not change the production model, Workflow Pack, prompt profile, sampling parameters, artifact/provenance schema, or pending_review teacher boundary. SSD-1B and style-adapter work remain evaluation evidence only. It adds no model selection, extension nodes, arbitrary workflows, cloud fallback, image editing, new platform implementation, generated images, model weights, caches, or Runtime artifacts.

Final boundary audit completed; Ready for Review authorized.
Do not merge without explicit merge authorization.