ha:core-internals

Develop homeassistant/ core itself — helpers/ API contracts, config_entries, websocket_api, bootstrap/setup/loader, auth, util. Framework-layer review criteria (C-laws + maintainer case law). Use when

SKILL.md

GitHub

Core Internals — Developing homeassistant/ Itself

Review criteria and API guidance for changing the Home Assistant framework layer: homeassistant/helpers/, core.py, bootstrap.py/setup.py/loader.py/runner.py, config_entries.py, components/websocket_api/, auth/, util/, script/ (incl. hassfest), and shared test infrastructure (tests/common.py, conftest files).

Evidence base: review-patterns-core-internals.md (1,012 maintainer review rows / 283 PRs / 12 reviewers, window 2025-07..2026-07), docs/framework-dev-laws.md (C1–C8), and the core developer-docs snapshot (API shapes in ${CLAUDE_SKILL_DIR}/references/core-api-shapes.md).

Roster tags: [OHF] = verified Open Home Foundation employee; [UNVERIFIED] = active reviewer, employment unconfirmed. [UNVERIFIED] enforcers carry weight as guidance ("some maintainers ask for…"), never as sole justification for a hard block.

Rule encoding: ESTABLISHED rules from the evidence file are stated as directives. CANDIDATE rules (fewer PRs / fewer distinct reviewers) are stated as "maintainers have asked for…" — follow them, but they are not blocking on their own.

When This Applies

Both conditions must hold:

  1. Core checkout — homeassistant/__init__.py exists AND script/ directory exists (the same detection /ha:init uses for the framework-development profile).
  2. The diff touches framework paths:
Area Paths
helpers homeassistant/helpers/**
core objects homeassistant/core.py, homeassistant/exceptions.py
boot chain homeassistant/bootstrap.py, setup.py, loader.py, runner.py, block_async_io.py
config entries homeassistant/config_entries.py, data_entry_flow.py
websocket_api homeassistant/components/websocket_api/** (the framework carve-out inside components/)
auth homeassistant/auth/**
util homeassistant/util/**
dev tooling script/** (hassfest, gen_requirements, Docker/build files)
test infra tests/common.py, tests/conftest.py, tests/components/conftest.py

This skill does NOT apply when the diff is confined to homeassistant/components/<domain>/ (integration work — use the integration-authoring skills) or custom_components/. The A–E laws (docs/iron-laws.md, docs/strong-defaults.md) still fully apply here; this skill adds the C tier on top and elevates core-style criteria (see the review checklist below) from secondary guidance to primary review criteria.

The C-Law Tier (summary — full text in docs/framework-dev-laws.md)

Do not restate rosters or citations from the law file; cite laws by ID.

Law Tier One-liner Relationship to A–E laws
C1 STRONG-DEFAULT A public helper's name and signature are its contract adjacent to PS17, scoped to public-API stability
C2 PROCESS-LAW One concern per PR strengthens PR1; carve-out: a new library ships with its first use
C3 PROCESS-LAW Breaking a public API is gated on a custom-integration search + calibrated deprecation extends PR3
C4 IRON-LAW ★ Nothing blocks the event loop; hot paths stay cheap reinforces P4 + adds hot-path frugality
C5 STRONG-DEFAULT Fail loud, never silent — but bad data must never crash boot shares the "never silent" theme with P2; the boot-survival half is net-new
C6 STRONG-DEFAULT Directional layering (util/ → helpers → components); no import cycles net-new at this layer
C7 STRONG-DEFAULT Typed, extensible interfaces shares the typing spine with P5/P6
C8 IRON-LAW New/changed core logic ships with tests + coverage restates P12/P13 at the framework layer

1. helpers/ — Public-API Contract Discipline (C1, C7)

A helper module's exported names, signatures, and docstrings ARE the framework's public API. Custom integrations import them directly; there is no stability boundary between you and thousands of downstream consumers.

The name is the contract — rename on drift, ambiguity, or misleading scope. Highest-volume rule in the corpus (30+ PRs; C1). Enforced by emontnemery[OHF], MartinHjelmare[OHF], arturpragacz[UNVERIFIED], abmantis[OHF], bdraco[OHF].

Declare event-loop safety in the name and decorator. Async-safe regular methods get @callback; coroutines and loop-only functions get the async_ prefix. (Cross-ref PS19 for the "coroutine that never awaits" half.) Enforced by emontnemery[OHF], justanotherariel[OHF], arturpragacz[UNVERIFIED].

Docstrings explain non-obvious intent; stale or wrong docstrings block merge (19 PRs). Enforced by emontnemery[OHF], MartinHjelmare[OHF], abmantis[OHF].

Public signatures are typed and extensible (C7) — TypedDict with correct totality (total=False when partial), kwargs or a dataclass so the signature can grow, a sentinel when None is a valid value, enums over magic numbers/strings (16 PRs). Enforced by arturpragacz[UNVERIFIED], emontnemery[OHF], MartinHjelmare[OHF].

2. Public-API Stability & Deprecation (C3)

Before changing or removing any exported helper/symbol:

  1. Search custom integrations for usage — pre-merge, not post-report (19 PRs). Enforced by bdraco[OHF], MartinHjelmare[OHF], emontnemery[OHF].
  2. Calibrate the deprecation period: 6 months if users can self-fix their config; 12 months if integrations must change code (9 PRs). Enforced by emontnemery[OHF], MartinHjelmare[OHF], joostlek[OHF], bdraco[OHF].
  3. Log the deprecation once via the report_usage helper, not ad-hoc warnings.
  4. Write a dev-blog post for anything custom integrations can see (C3/PR3).

For the full process (architecture-repo approval, dev-blog workflow, breaking-change sections), defer to C3 and the ha:architecture-process skill — do not restate it.

3. Layering & Module Placement (C6)

Direction of knowledge: util/ knows nothing about Home Assistant → helpers/ may know HA concepts → components sit on top. Domain/WS logic lives in its own module.

4. Registries, Entity & Coordinator Framework

5. Event-Loop Safety & Failure Visibility (C4, C5)

6. Hot-Path Discipline (C4 — the bdraco lens)

The state-write path runs at ~100k calls/minute on busy installs. Any diff touching core.py state writes, helpers/entity.py, registries, or the recorder path gets the performance review.

Cross-ref: the blocking-I/O half of C4 is mechanically checkable via P4's machinery; hot-path frugality is a reviewer call — profile or diff-inspect the write path.

7. config_entries Lifecycle

API shapes (entry states, lifecycle hooks, subentries, flow manager classes): see ${CLAUDE_SKILL_DIR}/references/core-api-shapes.md.

8. websocket_api

Registration mechanics (@websocket_command + @async_response + @require_admin, wired via async_register_command) are in the references file.

9. bootstrap / setup / loader — Boot Resilience (C5)

Staged-startup facts (STAGE 0 substages: labs → logging → frontend → recorder → zeroconf; timeouts per stage) are in the references file.

10. util/

11. script/ & hassfest

12. Tests & Coverage (C8)

  • New/changed core logic ships with tests that assert real behavior — uncovered lines and untested edge cases block merge; even deprecated code keeps basic coverage (14 PRs; C8 restating P12/P13 at the framework layer — framework paths sit outside the integration quality scale, so nothing else gates them). Enforced by bdraco[OHF], emontnemery[OHF], abmantis[OHF], frenck[OHF], MartinHjelmare[OHF].

  • Mechanical gate — run coverage on the touched module before claiming done:

    # helpers module
    python3 -m pytest tests/helpers/test_<module>.py \
        --cov=homeassistant.helpers.<module> --cov-report=term-missing
    # framework top-level module (config_entries, loader, setup, bootstrap, core)
    python3 -m pytest tests/test_<module>.py \
        --cov=homeassistant.<module> --cov-report=term-missing
    

    Every line your diff adds or changes must be exercised; behavior-assertion quality (does the test assert observable behavior, not implementation?) is a review call.

  • Maintainers have asked for no hidden magic in shared fixtures — follow the pytest-asyncio migration guide; keep fixtures readable, no clever lambdas (CANDIDATE, 13.1):

13. Cross-Cutting PR Hygiene (C2)


Core-Style Review Checklist (elevated from integration guidance)

Why this section exists: for integration authors, these criteria are shared Python/HA hygiene — they live in the strong defaults (notably PS20) and are inherited, not headline review criteria. For core contributors they are primary: the framework-review corpus (emontnemery's PART-B rules on scope, comments, tests, typing, and idioms) shows maintainers enforcing them as first-class, merge-relevant findings on framework diffs. Run this checklist on every framework-path diff before review:

Breaking a Public API — Decision Pointer

Any change visible to a custom integration (signature, removal, behavior, import path) routes through C3 (docs/framework-dev-laws.md) and the ha:architecture-process skill. Short form: custom-integration search → deprecation shim with report_usage → 6/12-month window → dev-blog post. Do not improvise the process here.

Recorded Tension (current behavior prevails)

MartinHjelmare[OHF] has argued that helpers/target.py using the entity "hidden" flag to influence target selection was a design mistake and should be inverted — "hidden ... should not matter for how the entity is used in automations" (https://github.com/home-assistant/core/pull/168860#discussion_r3128531028). This is a reviewer self-critique of existing framework behavior, not a documented rule change. Until the framework changes, preserve the current target.py semantics — do not "fix" this in passing.

Maintainer Review Map (who you will meet on a framework PR)

Reviewer Expect scrutiny on
MartinHjelmare [OHF] process (one concern per PR), backwards compat, try/except over check-then-act, tests for every branch
emontnemery [OHF] API design: naming, typed/total TypedDicts, sentinels, docstrings, caching, deprecation windows
arturpragacz [UNVERIFIED] composition over inheritance, kwargs/dataclasses, bootstrap-substage placement
abmantis [OHF] readability, circular imports, misplaced constants, monolith methods
bdraco [OHF] hot paths, state-write cost, recorder, cache scoping, breaking-change flags
edenhaus [OHF] boot resilience, validation placement, Docker/build-arg discipline
balloob [OHF] event-loop blocking, layering vetoes, circular-import routing
frenck [OHF] tooling safety, no internal third-party APIs, dangerous dev scripts

References

File Content
${CLAUDE_SKILL_DIR}/references/core-api-shapes.md Docs/code-observed API shapes: core.py objects, helpers/ map, config_entries classes, bootstrap stages, WS registration, auth model, recorder boundary
docs/framework-dev-laws.md C1–C8 full text with tiers, rosters, and relationship notes
docs/iron-laws.md, docs/strong-defaults.md The A–E base laws this skill layers on (P4, P10, P12/P13, PR1, PR3, PS17, PS19, PS20)