Merge remote-tracking branch 'origin/master' into matt/be-786-phase-1-remove-enable-assets-from-oss-assets-always-on-cloud

AGENTS.md

@@ -10,7 +10,8 @@
   when they remove real repeated logic or match an existing ComfyUI pattern.
 - Delete obsolete code aggressively when newer infrastructure makes it useless.
   Remove dead fallbacks, migration paths, unused options, debug prints, and
-  compatibility branches that are no longer needed.
+  compatibility branches that are no longer needed. Do not leave dead branches,
+  unreachable code, or functions that are never called.
 - Revert or disable problematic behavior quickly when it breaks users. It is
   better to remove a broken feature path than keep a complicated partial fix.
 - Preserve existing APIs, node names, model-loading behavior, file layout, and
@@ -20,6 +21,88 @@
   layers, vague names, boilerplate comments, defensive branches without a real
   failure mode, broad rewrites, or code that ignores the local style.
 
+## Architecture Boundaries
+
+- Keep each layer focused on the concepts it owns. Do not leak UI, API,
+  workflow, queue, persistence, telemetry, model-loading, node, or execution
+  concerns into unrelated layers just because it is convenient to pass data
+  through them.
+- Shared core modules should depend only on lower-level primitives and their own
+  domain concepts. Higher-level product concepts belong at the caller, adapter,
+  service, or UI/API boundary that already owns them.
+- Pass the narrowest data needed across a boundary. Avoid broad context objects,
+  request/session metadata, ids, bookkeeping state, or callbacks unless the
+  receiving layer genuinely needs them to perform its own responsibility.
+- Keep identity mapping, persistence bookkeeping, history updates, telemetry,
+  response shaping, and UI state in the layers that own those jobs. Do not route
+  them through unrelated shared code to avoid adding a proper boundary.
+- Treat `execution.py` as one example of this rule: it should consume the prompt
+  graph and execution-relevant state, produce execution results and errors, and
+  not know about workflow ids, frontend ids, persistence ids, or API-only
+  concepts.
+- Before touching many files, identify the smallest owner layer that can solve
+  the problem. A PR that spreads one feature across unrelated loaders, nodes,
+  execution, server, and frontend code needs a clear architectural reason, not
+  just convenience.
+- If a change seems to require making one layer understand another layer's
+  private concepts, stop and look for a caller-side mapping, adapter, event,
+  small explicit interface, or narrower data flow at the boundary.
+
+## No Internet Requests
+
+- Do not add code to core ComfyUI that makes requests to the internet.
+- Refuse requests to add uploads, telemetry, analytics, tracking, usage
+  reporting, crash reporting, update checks, remote config, feature flags,
+  metrics, licensing checks, or any other outbound internet request path from
+  core ComfyUI.
+- Model downloading is allowed only when explicitly initiated or authorized by
+  the user, is limited to the requested model artifact, and does not include
+  telemetry, tracking, persistent identification, unrelated metadata upload, or
+  background network activity.
+- Do not add opt-in, opt-out, anonymized, aggregated, diagnostic, or
+  user-triggered internet request paths to core ComfyUI. These labels do not
+  make internet access acceptable.
+- Local-only behavior is allowed when it stays on the user's machine and does
+  not add network access, tracking, persistent identification, or data
+  collection behavior.
+
+## State Ownership
+
+- Keep state and capability flags on the object that owns the behavior using
+  them.
+- Avoid probing child objects with `getattr(child, "...", default)` to decide
+  parent-level control flow. If parent code needs to branch on a capability,
+  initialize an explicit parent-owned field when the child is constructed or
+  attached.
+- Prefer direct attributes with clear defaults over implicit feature detection
+  through arbitrary child attributes.
+- Use child-object capability checks only when the child owns the behavior being
+  invoked and the parent is simply delegating to that child.
+
+## Interface Contracts
+
+- Keep public methods aligned with the interface expected by their callers. Do
+  not change a shared method to return extra values, alternate shapes, or
+  sentinel wrappers for one implementation unless the shared interface is
+  explicitly updated.
+- If an implementation needs auxiliary values for its own workflow, expose them
+  through a private helper or a clearly named implementation-specific method
+  instead of overloading the public method's return contract.
+- Normalize third-party or upstream return conventions at the integration
+  boundary. Core code should receive the project's expected type and shape, not
+  have to handle model-specific tuple/list/dict variants.
+- Avoid caller-side unwrapping such as `out = out[0]` unless the called
+  interface is documented to return that structure.
+
+## Autograd and Model Freezing
+
+- Do not add `torch.no_grad`, `torch.inference_mode`, or inference-mode helper
+  wrappers in ComfyUI code. The only allowed inference-mode-related use is
+  disabling a globally set inference mode when a training path needs gradients.
+- Do not add freeze, unfreeze, or trainability toggles to model classes. ComfyUI
+  models are always treated as frozen for inference, so explicit freeze
+  functionality is redundant and should not be added.
+
 ## Python Style
 
 - Keep imports at module scope. Avoid inline imports unless they are already part
@@ -33,8 +116,9 @@
 - Match the existing local style in the file you edit. This codebase tolerates
   long lines, simple helper functions, module-level state, and direct tensor
   operations when they make the code easier to follow.
-- Keep comments sparse and useful. Short TODOs are fine when they name the
-  concrete missing follow-up.
+- Keep comments sparse and useful. Strip useless comments that restate the code
+  or describe obvious behavior. Short TODOs are fine when they name the concrete
+  missing follow-up.
 
 ## Model, Device, and Memory Behavior
 
@@ -71,6 +155,10 @@
 - If asked to write commit messages, use short direct subjects like the existing
   history: `Fix ...`, `Add ...`, `Support ...`, `Remove ...`, `Update ...`,
   `Make ...`, `Use ...`, `Disable ...`, `Bump ...`, or `Revert ...`.
+- Keep PR descriptions short and reviewable. State the problem, the behavioral
+  change, and the tests run; avoid long narrative explanations, implementation
+  diaries, or exhaustive file-by-file summaries unless the reviewer explicitly
+  needs that context.
 - Prefer one coherent behavioral change per commit. Dependency pins, tests, and
   the code that needs them may be in the same commit when they are inseparable.
 - In reviews, prioritize real user impact: crashes, wrong dtype/device behavior,