contracts.rules_suspense_defer

Undiscoverable Suspense deferred-block contract.

Suspense(...)defers awaitable context values: the shell renders with each deferred key set to theDEFERREDsentinel, then every block whose depends_onreferences a deferred key is re-rendered and streamed as an OOB swap. Blocks are discovered automatically via kida'sblock_metadata().

When a deferred key is used by the template (it self-declares the key via "<NAME>" in __chirp_defer_pending__ or the <NAME> is deferredtest) but no block depends on it, auto-discovery finds nothing to re-render. At runtimerender_suspense already fails loud (ConfigurationErrorbefore any shell bytes flush), but the developer only learns when a request hits the route. This rule promotes that failure to a startupapp.check() WARNINGand recommends thedefer_blocks=(...)escape hatch.

Detection is scoped to templates that self-declare their defer keys (the same reliable static signalchirp.contracts.rules_defer_falsyuses), so it cannot statically know whichSuspensekwargs are awaitable but also never false-positives on arbitrary{% if x %} or sync-only Suspenseusage. Templates whose route handler passesdefer_blocks=bypass auto-discovery entirely, so they are exempt. Severity isWARNING-- the rule ships informational by default and can be promoted toERRORvia app.override_contract_severity("suspense_defer", Severity.ERROR)in CI.