Establish a centrally managed logging port with architecture enforcement against direct logger invocation

[leynos]

Summary

episodic/logging.py is intended as the project's logging seam, exposing
log_info, log_warning, and log_error over femtologging. In practice most
logging bypasses it: 29 of 48 logging call sites in episodic/ call a
logger method directly.

$ grep -rn "log_info(\|log_warning(\|log_error(" --include=*.py episodic/ \
    | grep -v "def log_\|episodic/logging.py" | wc -l
19
$ grep -rEn "\b(logger|_log|_logger|effective_log)\.(debug|info|warning|error|critical|log)\(" \
    --include=*.py episodic/ | grep -v "episodic/logging.py" | wc -l
29

The bypassing sites are in episodic/concurrent_interpreters.py (8),
episodic/canonical/storage/migration_check.py (7),
episodic/generation/chapter_marker_generator.py (4),
episodic/worker/runtime.py (2), episodic/qa/chrono.py (2),
episodic/qa/chrono_langgraph.py (2), and one each in
episodic/api/authorization.py, episodic/llm/openai_api/utils.py,
episodic/canonical/storage/uow.py, episodic/canonical/services.py, and
episodic/canonical/ingestion_service.py.

There is nothing wrong with any individual call. The problem is that the seam
is advisory, so any cross-cutting change to logging behaviour silently covers
39% of the codebase and misses the rest, with no gate to say so.

Why this surfaced now

Roadmap item 4.1.3 (request correlation) needs every log line a request produces
to carry that request's correlation identifier. femtologging cannot carry
ambient structured context — see
leynos/femtologging#417, #418, and #419 — so the identifier has to be attached
at the seam. The execplan
(docs/execplans/4-1-3-integrate-request-correlation.md) originally claimed
that decorating the three helpers gave complete coverage. It does not, and two
of the uncovered sites are precisely the ones the roadmap names: the
authorization denial (#287) and _log_error_event in
episodic/llm/openai_api/utils.py:108-111, the structured provider-error path
that fires on the provider failures the feature exists to correlate.

4.1.3 will close those two by hand. This issue is about making the seam
enforceable so the next cross-cutting change does not have to rediscover the
same 29 sites.

Proposal

1. Make episodic/logging.py an explicit, documented logging port.

Give it the full level surface the codebase actually needs — it currently lacks
log_debug, which is one reason episodic/api/authorization.py calls
logger.log(LogLevel.DEBUG, ...) directly — and document the contract in
docs/developers-guide.md: what a call site may assume, what the port
guarantees to attach (correlation identifier, and whatever comes later), and
why the raw femtologging logger is not the public surface.

2. Enforce the import edge with hecate.

hecate can gate this, but only after a configuration change:
include_external_packages defaults to False
(hecate/config.py:91) and [tool.hecate] at pyproject.toml:785 does not set
it, so today the checker sees zero third-party import edges. Setting it to
true and declaring a group that permits femtologging only from
episodic.logging would make from femtologging import get_logger anywhere
else a build failure.

Two cautions:

• Turning on include_external_packages will surface every other external edge
  in the repository at once. Expect a first pass of classifying falcon,
  sqlalchemy, celery, httpx, and friends into groups.
• hecate matches on first matching prefix, so a broad prefix silently voids
  later groups while still reporting a pass. Order the new groups carefully and
  add a fixture under tests/fixtures/architecture/ that would fail if the
  rule were shadowed.

3. Close the gap hecate cannot see.

hecate reasons about import edges, not call sites. It cannot catch
logger = get_logger(__name__) followed by logger.info(...), because the
import is legitimate. Two options, not mutually exclusive:

• Type the handle. Have the port return an opaque handle that does not
  expose .info/.debug/.log, so a direct call is a typecheck failure under
  ty and pyright. Strongest option, and it costs a Protocol rather than a
  new tool.
• Add a lint rule. The repository already runs a custom Pylint plugin
  (df12-python-lints) under CPython 3.14, which is the natural home for a
  check banning level-method calls on objects returned by get_logger.

4. Migrate the 29 sites, ideally in one mechanical commit per package so the
diff stays reviewable.

Acceptance

• docs/developers-guide.md documents the port and the rule.
• make check-architecture fails on a fixture that imports femtologging
  outside episodic/logging.py.
• Either make typecheck or make lint fails on a fixture that calls a level
  method directly.
• grep for direct logger calls in episodic/ returns only episodic/logging.py.

Related

• log_context fields never reach records emitted through get_logger femtologging#417, #418, #419 — why the context cannot be attached
  further down the stack.
• docs/execplans/4-1-3-integrate-request-correlation.md, Decision D5 and
  milestone EP-M3b.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Convert episodic/logging.py into a port that returns an opaque LoggerHandle and offers one wrapper per level, so direct level calls fail type checking.
• Migrate all twenty-nine bypassing sites onto the wrappers, package by package, and move the three stdlib-logging modules onto the port.
• Enforce the import edge with Hecate by enabling include_external_packages, classifying external packages into ordered groups, and adding a failing fixture that also guards against group shadowing.
• Gate direct calls with the opaque handle plus a targeted ty fixture and a repo-local scanner test, and document the port and both rules in the developers' guide.

Design Choices

Design Choice 1: Which mechanism closes the call-site gap that Hecate cannot see?

Options Considered:

1. Type the handle. Return an opaque handle with no level methods, so a direct call fails ty.
2. Add a Pylint rule inside df12-python-lints.
3. Add a repo-local AST scanner test.

Chosen Option: 1

Rationale: Choose Option 1 as the primary gate, because df12-python-lints is an external pin that cannot be edited here, and an opaque handle costs one Protocol/wrapper rather than a new tool. Add a repo-local AST scanner test (Option 3) as a lightweight standing gate for the grep acceptance criterion.

Hecate reasons about import edges, not call sites, so logger.info(...) after a legitimate get_logger import needs a separate gate.

Design Choice 2: How does `include_external_packages = true` classify third-party edges, and how does `allowed` reference them?

Options Considered:

1. Create dedicated groups for external packages: one restricted logging_backend group for femtologging and one broad external_libraries group for the rest, then add both to the relevant allowed lists.
2. Rely on Hecate treating unclassified external edges as permitted, and restrict only femtologging.

Chosen Option: 1

Rationale: Choose Option 1, because the ticket states that enabling the flag surfaces every external edge and requires a classification pass, so explicit groups form the safe, deterministic model.

The repository has no Hecate documentation for external-package classification, and external knowledge sources returned nothing.

Design Choice 3: How does the migration handle sites that pass `extra={...}` structured fields (in `concurrent_interpreters.py`, `qa/chrono.py`, `qa/chrono_langgraph.py`)?

Options Considered:

1. Fold the structured fields into the pre-formatted message string, following the JSON pattern already used by _log_error_event.
2. Extend the port to accept and serialise **fields.

Chosen Option: 1

Rationale: Choose Option 1, because it keeps the port's single formatting contract and matches the existing _log_error_event precedent, and it avoids a new schema.

femtologging and the port carry no ambient structured context.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Formalise the logging port with an opaque handle

This phase turns the advisory seam into a port. The port returns an opaque handle that exposes no level methods. It provides one wrapper function per level. A direct level-method call on the handle then fails type checking.

Task 1: Introduce the opaque handle and complete the level surface

Give episodic/logging.py a handle type and the full set of level wrappers.

• Add a LoggerHandle type to episodic/logging.py. Make it wrap a private _CompatibleLogger and expose no debug/info/warning/error/critical/exception/log methods.
• Change get_logger(name) and its getLogger alias to build the femtologging logger, wrap it in a LoggerHandle, and return the handle. Stop re-exporting femtologging's raw get_logger as the public surface.
• Keep the existing _SupportsConvenienceLog/_SupportsLogMethod protocols and the eager percent-formatting plus convenience-first, .log()-fallback dispatch logic. Move that logic to operate on the handle's wrapped logger.
• Add log_debug and log_exception alongside log_info/log_warning/log_error. Make log_exception default exc_info=True. Make every wrapper accept a LoggerHandle.
• Leave LogLevel and configure_logging unchanged. Update __all__ to add LoggerHandle, log_debug, and log_exception.
• Provide an internal constructor path so tests can wrap a spy logger in a LoggerHandle.

Task 2: Update port tests and snapshots

Keep the regression suite aligned with the new handle contract.

• Update tests/test_logging.py so the spy loggers (_SpyLogger, _LogOnlySpyLogger) are wrapped in LoggerHandle before being passed to the wrappers.
• Add cases for log_debug and log_exception, including the .log() fallback path and the exc_info=True default of log_exception.
• Refresh tests/__snapshots__/test_logging.ambr for the new call-argument tuples.
• Preserve the configure_logging normalisation tests and the femtologging end-to-end handler test unchanged.

🤖 Prompt for AI agents

Implement Phase 1: turn `episodic/logging.py` into an explicit port that returns
an opaque `LoggerHandle`, and update the test suite to match.

For `episodic/logging.py`:
- Add a `LoggerHandle` type. Wrap a private `_CompatibleLogger`. Do not expose
`debug`/`info`/`warning`/`error`/`critical`/`exception`/`log` methods on
`LoggerHandle`.
- Change `get_logger(name)` and its `getLogger` alias to build the femtologging
logger, wrap it in a `LoggerHandle`, and return the handle. Stop re-exporting
femtologging's raw `get_logger` as the public surface.
- Keep the existing `_SupportsConvenienceLog`/`_SupportsLogMethod` protocols.
Keep the eager percent-formatting plus convenience-first, `.log()`-fallback
dispatch logic. Move that logic to operate on the handle's wrapped logger.
- Add `log_debug` and `log_exception` wrapper functions alongside
`log_info`/`log_warning`/`log_error`. Set `exc_info=True` as the default for
`log_exception`. Make every wrapper accept a `LoggerHandle`.
- Leave `LogLevel` and `configure_logging` unchanged. Add `LoggerHandle`,
`log_debug`, and `log_exception` to `__all__`.
- Provide an internal constructor path so tests can wrap a spy logger in a
`LoggerHandle`.

For the test suite:
- Update `tests/test_logging.py` so the spy loggers (`_SpyLogger`,
`_LogOnlySpyLogger`) get wrapped in `LoggerHandle` before being passed to the
wrappers.
- Add test cases for `log_debug` and `log_exception`, covering the `.log()`
fallback path and the `exc_info=True` default of `log_exception`.
- Refresh `tests/__snapshots__/test_logging.ambr` for the new call-argument
tuples.
- Keep the `configure_logging` normalisation tests and the femtologging
end-to-end handler test unchanged.

Phase 2: Migrate the twenty-nine call sites onto the port

This phase routes every logging call through the port wrappers. Group the work per package so each diff stays reviewable. Translate every direct level method to the matching wrapper. Convert logger.log(LogLevel.DEBUG, ...) to log_debug. Pass values as percent-style format arguments rather than f-strings. Fold any extra={...} fields into the pre-formatted message.

Task 1: Migrate the canonical package

• Update episodic/canonical/services.py, episodic/canonical/ingestion_service.py, and episodic/canonical/storage/uow.py to call log_info with percent-style arguments instead of logger.info(f"...").
• Update episodic/canonical/storage/migration_check.py to route its error/info/exception calls through log_error/log_info/log_exception, replacing the f-string error call with format arguments.

Task 2: Migrate the generation and worker modules

• Update episodic/generation/chapter_marker_generator.py and its logger source episodic/generation/chapter_marker_common.py to use log_warning/log_info on the handle. Keep the existing log_info helper call.
• Update episodic/worker/runtime.py to replace the local _log_info helper and the log_exception = logger.exception alias with log_info and log_exception from the port.

Task 3: Migrate the API and LLM modules

• Update episodic/api/authorization.py: replace logger.log(LogLevel.DEBUG, f"...") in _log_authorization_denial with log_debug and format arguments. Keep the existing log_warning call. Do not change the surrounding exception handling unless the migration cannot compile; flag the suspect except clause for follow-up rather than expanding scope.
• Update episodic/llm/openai_api/utils.py: route _log_error_event through log_error. Make the _log_override contextvar and the module logger _log hold LoggerHandle values.

Task 4: Move the stdlib-logging modules onto the port

• Update episodic/concurrent_interpreters.py, episodic/qa/chrono.py, and episodic/qa/chrono_langgraph.py to obtain a handle via episodic.logging.get_logger instead of stdlib logging.getLogger.
• Route their debug/info/warning/error/exception calls through the matching port wrappers.
• Fold each extra={...} payload into the pre-formatted message, following the JSON pattern used by _log_error_event, because the port carries no structured context.

🤖 Prompt for AI agents

Implement Phase 2: migrate every one of the twenty-nine bypassing call sites
onto the port wrappers from `episodic/logging.py`. Group the migration by
package so each diff stays reviewable. Translate every direct level method call
to the matching wrapper. Convert `logger.log(LogLevel.DEBUG, ...)` to
`log_debug`. Pass values as percent-style format arguments rather than
f-strings. Fold any `extra={...}` fields into the pre-formatted message.

Canonical package: update `episodic/canonical/services.py`,
`episodic/canonical/ingestion_service.py`, and
`episodic/canonical/storage/uow.py` to call `log_info` with percent-style
arguments instead of `logger.info(f"...")`. Update
`episodic/canonical/storage/migration_check.py` to route its
`error`/`info`/`exception` calls through `log_error`/`log_info`/`log_exception`,
and replace the f-string error call with format arguments.

Generation and worker modules: update
`episodic/generation/chapter_marker_generator.py` and its logger source
`episodic/generation/chapter_marker_common.py` to use `log_warning`/`log_info`
on the handle, keeping the existing `log_info` helper call. Update
`episodic/worker/runtime.py` to replace the local `_log_info` helper and the
`log_exception = logger.exception` alias with `log_info` and `log_exception`
from the port.

API and LLM modules: in `episodic/api/authorization.py`, replace
`logger.log(LogLevel.DEBUG, f"...")` in `_log_authorization_denial` with
`log_debug` and format arguments, and keep the existing `log_warning` call. Do
not change the surrounding exception handling unless the migration cannot
compile; flag any suspect `except` clause for follow-up instead of expanding
scope. In `episodic/llm/openai_api/utils.py`, route `_log_error_event` through
`log_error`, and make the `_log_override` contextvar and the module logger
`_log` hold `LoggerHandle` values.

Stdlib-logging modules: update `episodic/concurrent_interpreters.py`,
`episodic/qa/chrono.py`, and `episodic/qa/chrono_langgraph.py` to obtain a
handle via `episodic.logging.get_logger` instead of stdlib `logging.getLogger`.
Route their `debug`/`info`/`warning`/`error`/`exception` calls through the
matching port wrappers. Fold each `extra={...}` payload into the pre-formatted
message, following the JSON pattern used by `_log_error_event`, because the port
carries no structured context.

Phase 3: Enforce the femtologging import edge with Hecate

This phase makes from femtologging import ... outside episodic.logging a build failure. It enables external-package tracking, classifies external packages into groups with correct first-match ordering, extends the fixture harness, and adds a failing fixture that also guards against group shadowing.

Task 1: Configure Hecate groups and external-package tracking

• In pyproject.toml under [tool.hecate], set include_external_packages = true.
• Add a logging_port group with prefix episodic.logging, placed before the existing episodic groups. Add a logging_backend group with prefix femtologging. Make logging_port the only group whose allowed list includes logging_backend.
• Add an external_libraries group covering the other third-party packages the repository imports (for example falcon, sqlalchemy, celery, httpx, openai, langgraph, alembic, pydantic). Add external_libraries and logging_port to the allowed list of every episodic group, because every layer imports the port.
• Order the groups so logging_backend matches femtologging before external_libraries, and so external_libraries prefixes never include femtologging. Respect the first-match ordering caution.
• Determine how Hecate treats standard-library edges under the flag. If it reports them, add a permissive standard-library group or configure Hecate to ignore them, then add that group to every allowed list.

Task 2: Extend the architecture fixture harness

• Extend tests/architecture_hecate_config.py to emit a config variant that sets include_external_packages = true and adds a logging_port group (prefix <package>.logging) and a logging_backend group (prefix femtologging), alongside the existing permissive groups.
• Keep the current five-group behaviour for existing fixtures unchanged. Add the variant behind an explicit selector rather than altering the default template.

Task 3: Add the femtologging boundary fixture and wire tests

• Create tests/fixtures/architecture/femtologging_outside_logging_port/ with __init__.py, a logging.py module that imports femtologging (the sanctioned port, allowed), and an api.py module that imports femtologging directly (must fail).
• Add the new fixture to the failing-case parametrize list in tests/test_architecture_enforcement.py, asserting return code 1, ARCH001, the importer module, and femtologging in the diagnostic. This failing assertion also guards against group shadowing, because a shadowed rule would wrongly pass.
• Add a matching BDD scenario in tests/features/architecture_enforcement.feature and a step binding in tests/steps/test_architecture_enforcement_steps.py.
• Verify the production check still passes by running make check-architecture after the config change.

🤖 Prompt for AI agents

Implement Phase 3: make `from femtologging import ...` outside
`episodic.logging` a build failure by configuring Hecate.

Configure groups and external-package tracking:
- In `pyproject.toml` under `[tool.hecate]`, set `include_external_packages =
true`.
- Add a `logging_port` group with prefix `episodic.logging`, placed before the
existing episodic groups. Add a `logging_backend` group with prefix
`femtologging`. Make `logging_port` the only group whose `allowed` list includes
`logging_backend`.
- Add an `external_libraries` group covering the other third-party packages the
repository imports (for example `falcon`, `sqlalchemy`, `celery`, `httpx`,
`openai`, `langgraph`, `alembic`, `pydantic`). Add `external_libraries` and
`logging_port` to the `allowed` list of every episodic group, because every
layer imports the port.
- Order the groups so `logging_backend` matches `femtologging` before
`external_libraries`, and so `external_libraries` prefixes never include
`femtologging`. Respect the first-match ordering caution.
- Determine how Hecate treats standard-library edges under the flag. If it
reports them, add a permissive standard-library group or configure Hecate to
ignore them, then add that group to every `allowed` list.

Extend the fixture harness:
- Extend `tests/architecture_hecate_config.py` to emit a config variant that
sets `include_external_packages = true` and adds a `logging_port` group (prefix
`<package>.logging`) and a `logging_backend` group (prefix `femtologging`),
alongside the existing permissive groups.
- Keep the current five-group behaviour for existing fixtures unchanged. Add the
variant behind an explicit selector rather than altering the default template.

Add the femtologging boundary fixture and wire tests:
- Create `tests/fixtures/architecture/femtologging_outside_logging_port/` with
`__init__.py`, a `logging.py` module that imports `femtologging` (the sanctioned
port, allowed), and an `api.py` module that imports `femtologging` directly
(must fail).
- Add the new fixture to the failing-case parametrize list in
`tests/test_architecture_enforcement.py`, asserting return code `1`, `ARCH001`,
the importer module, and `femtologging` in the diagnostic. This failing
assertion also guards against group shadowing, because a shadowed rule would
wrongly pass.
- Add a matching BDD scenario in
`tests/features/architecture_enforcement.feature` and a step binding in
`tests/steps/test_architecture_enforcement_steps.py`.
- Verify the production check still passes by running `make check-architecture`
after the config change.

Phase 4: Enforce the direct-call rule

This phase gates direct level-method calls. The opaque handle already makes a direct call a type error in the real tree. Add a negative fixture and a targeted ty test to satisfy the fixture acceptance criterion, and add a scanner test to hold the grep criterion.

Task 1: Add a negative type-check fixture and test

• Create a negative fixture outside the main ty scope that acquires a LoggerHandle from the port and calls .info(...) on it directly.
• Add a test that runs ty check on that fixture path in isolation and asserts a non-zero exit with an attribute or type error, mirroring the subprocess pattern in tests/test_architecture_enforcement.py.
• Confirm the fixture is excluded from make typecheck so the standing type check stays green.

Task 2: Add a repo-local scanner test for the grep criterion

• Add a test that globs episodic/**/*.py, excludes episodic/logging.py, and asserts no attribute call matching \.(debug|info|warning|error|critical|log)\( on a logger-bound name remains.
• Follow the re.compile plus Path.read_text idiom from tests/test_ci_workflow_contract.py, or the ast.parse glob-and-walk idiom from scripts/tests/test_typos_rollout.py.
• Keep the assertion set-based and report every offending file, so a regression names the exact site.

🤖 Prompt for AI agents

Implement Phase 4: add enforcement for the direct-call rule. The opaque handle
already makes a direct call a type error in the real tree, so add tests that
hold this gate.

Add a negative type-check fixture and test:
- Create a negative fixture outside the main `ty` scope that acquires a
`LoggerHandle` from the port and calls `.info(...)` on it directly.
- Add a test that runs `ty check` on that fixture path in isolation and asserts
a non-zero exit with an attribute or type error, mirroring the subprocess
pattern in `tests/test_architecture_enforcement.py`.
- Confirm the fixture is excluded from `make typecheck` so the standing type
check stays green.

Add a repo-local scanner test for the grep criterion:
- Add a test that globs `episodic/**/*.py`, excludes `episodic/logging.py`, and
asserts no attribute call matching `\.(debug|info|warning|error|critical|log)\(`
remains on a logger-bound name.
- Follow the `re.compile` plus `Path.read_text` idiom from
`tests/test_ci_workflow_contract.py`, or the `ast.parse` glob-and-walk idiom
from `scripts/tests/test_typos_rollout.py`.
- Keep the assertion set-based, and report every offending file, so a regression
names the exact site.

Phase 5: Document the port and the rule

This phase records the contract and the enforcement so future cross-cutting logging changes have one place to change.

Task 1: Document the logging port contract

• Update the ## Logging section of docs/developers-guide.md. Replace the current guidance that prefers direct logger methods. State that call sites must obtain a LoggerHandle from get_logger and emit through log_debug/log_info/log_warning/log_error/log_exception.
• Document what a call site may assume, what the port guarantees to attach later (the correlation identifier), and why the raw femtologging logger is not the public surface.
• Style the new subsection like the existing ### Generation-run domain ports and ## Observability port abstractions sections.

Task 2: Document the architecture and call-site rules

• Update the ### Architecture enforcement section of docs/developers-guide.md. Describe include_external_packages = true, the new logging_port, logging_backend, and external_libraries groups, and the first-match ordering that keeps femtologging restricted.
• Record the direct-call rule and the two gates that enforce it: the opaque handle under ty and the scanner test.

🤖 Prompt for AI agents

Implement Phase 5: document the logging port and the enforcement rules in
`docs/developers-guide.md` so future cross-cutting logging changes have one
place to change.

Document the logging port contract:
- Update the `## Logging` section. Replace the current guidance that prefers
direct logger methods. State that call sites must obtain a `LoggerHandle` from
`get_logger` and emit through
`log_debug`/`log_info`/`log_warning`/`log_error`/`log_exception`.
- Document what a call site may assume, what the port guarantees to attach later
(the correlation identifier), and why the raw femtologging logger is not the
public surface.
- Style the new subsection like the existing `### Generation-run domain ports`
and `## Observability port abstractions` sections.

Document the architecture and call-site rules:
- Update the `### Architecture enforcement` section. Describe
`include_external_packages = true`, the new `logging_port`, `logging_backend`,
and `external_libraries` groups, and the first-match ordering that keeps
`femtologging` restricted.
- Record the direct-call rule and the two gates that enforce it: the opaque
handle under `ty` and the scanner test.

Research

episodic/logging.py is the logging seam over the Rust-backed femtologging dependency. It defines LogLevel, configure_logging, and the log_info/log_warning/log_error wrappers, and it re-exports femtologging's get_logger/getLogger unchanged. The wrappers format messages eagerly with percent-style arguments, then dispatch to a convenience method with a .log() fallback, because femtologging does not support lazy formatting or structured context.

Architecture boundaries are enforced by Hecate, configured under [tool.hecate] in pyproject.toml with five ordered groups matched on first-matching prefix; fixtures under tests/fixtures/architecture/ drive tests/test_architecture_enforcement.py and a BDD feature.

Type checking runs ty (pinned to 0.0.32) with no project-level config. The custom Pylint plugin df12-python-lints is an external git pin and cannot be edited in this repository.

Twenty-nine call sites across eleven modules bypass the seam; three of them use stdlib logging.getLogger instead of the port.

Note: The referenced execplan docs/execplans/4-1-3-integrate-request-correlation.md does not exist in this checkout. Do not create or edit it. This plan only makes the seam enforceable, as the ticket states.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: turn `episodic/logging.py` into an explicit port that returns
an opaque `LoggerHandle`, and update the test suite to match.

For `episodic/logging.py`:
- Add a `LoggerHandle` type. Wrap a private `_CompatibleLogger`. Do not expose
`debug`/`info`/`warning`/`error`/`critical`/`exception`/`log` methods on
`LoggerHandle`.
- Change `get_logger(name)` and its `getLogger` alias to build the femtologging
logger, wrap it in a `LoggerHandle`, and return the handle. Stop re-exporting
femtologging's raw `get_logger` as the public surface.
- Keep the existing `_SupportsConvenienceLog`/`_SupportsLogMethod` protocols.
Keep the eager percent-formatting plus convenience-first, `.log()`-fallback
dispatch logic. Move that logic to operate on the handle's wrapped logger.
- Add `log_debug` and `log_exception` wrapper functions alongside
`log_info`/`log_warning`/`log_error`. Set `exc_info=True` as the default for
`log_exception`. Make every wrapper accept a `LoggerHandle`.
- Leave `LogLevel` and `configure_logging` unchanged. Add `LoggerHandle`,
`log_debug`, and `log_exception` to `__all__`.
- Provide an internal constructor path so tests can wrap a spy logger in a
`LoggerHandle`.

For the test suite:
- Update `tests/test_logging.py` so the spy loggers (`_SpyLogger`,
`_LogOnlySpyLogger`) get wrapped in `LoggerHandle` before being passed to the
wrappers.
- Add test cases for `log_debug` and `log_exception`, covering the `.log()`
fallback path and the `exc_info=True` default of `log_exception`.
- Refresh `tests/__snapshots__/test_logging.ambr` for the new call-argument
tuples.
- Keep the `configure_logging` normalisation tests and the femtologging
end-to-end handler test unchanged.
===============================================================================

Task: 2

Implement Phase 2: migrate every one of the twenty-nine bypassing call sites
onto the port wrappers from `episodic/logging.py`. Group the migration by
package so each diff stays reviewable. Translate every direct level method call
to the matching wrapper. Convert `logger.log(LogLevel.DEBUG, ...)` to
`log_debug`. Pass values as percent-style format arguments rather than
f-strings. Fold any `extra={...}` fields into the pre-formatted message.

Canonical package: update `episodic/canonical/services.py`,
`episodic/canonical/ingestion_service.py`, and
`episodic/canonical/storage/uow.py` to call `log_info` with percent-style
arguments instead of `logger.info(f"...")`. Update
`episodic/canonical/storage/migration_check.py` to route its
`error`/`info`/`exception` calls through `log_error`/`log_info`/`log_exception`,
and replace the f-string error call with format arguments.

Generation and worker modules: update
`episodic/generation/chapter_marker_generator.py` and its logger source
`episodic/generation/chapter_marker_common.py` to use `log_warning`/`log_info`
on the handle, keeping the existing `log_info` helper call. Update
`episodic/worker/runtime.py` to replace the local `_log_info` helper and the
`log_exception = logger.exception` alias with `log_info` and `log_exception`
from the port.

API and LLM modules: in `episodic/api/authorization.py`, replace
`logger.log(LogLevel.DEBUG, f"...")` in `_log_authorization_denial` with
`log_debug` and format arguments, and keep the existing `log_warning` call. Do
not change the surrounding exception handling unless the migration cannot
compile; flag any suspect `except` clause for follow-up instead of expanding
scope. In `episodic/llm/openai_api/utils.py`, route `_log_error_event` through
`log_error`, and make the `_log_override` contextvar and the module logger
`_log` hold `LoggerHandle` values.

Stdlib-logging modules: update `episodic/concurrent_interpreters.py`,
`episodic/qa/chrono.py`, and `episodic/qa/chrono_langgraph.py` to obtain a
handle via `episodic.logging.get_logger` instead of stdlib `logging.getLogger`.
Route their `debug`/`info`/`warning`/`error`/`exception` calls through the
matching port wrappers. Fold each `extra={...}` payload into the pre-formatted
message, following the JSON pattern used by `_log_error_event`, because the port
carries no structured context.
===============================================================================

Task: 3

Implement Phase 3: make `from femtologging import ...` outside
`episodic.logging` a build failure by configuring Hecate.

Configure groups and external-package tracking:
- In `pyproject.toml` under `[tool.hecate]`, set `include_external_packages =
true`.
- Add a `logging_port` group with prefix `episodic.logging`, placed before the
existing episodic groups. Add a `logging_backend` group with prefix
`femtologging`. Make `logging_port` the only group whose `allowed` list includes
`logging_backend`.
- Add an `external_libraries` group covering the other third-party packages the
repository imports (for example `falcon`, `sqlalchemy`, `celery`, `httpx`,
`openai`, `langgraph`, `alembic`, `pydantic`). Add `external_libraries` and
`logging_port` to the `allowed` list of every episodic group, because every
layer imports the port.
- Order the groups so `logging_backend` matches `femtologging` before
`external_libraries`, and so `external_libraries` prefixes never include
`femtologging`. Respect the first-match ordering caution.
- Determine how Hecate treats standard-library edges under the flag. If it
reports them, add a permissive standard-library group or configure Hecate to
ignore them, then add that group to every `allowed` list.

Extend the fixture harness:
- Extend `tests/architecture_hecate_config.py` to emit a config variant that
sets `include_external_packages = true` and adds a `logging_port` group (prefix
`<package>.logging`) and a `logging_backend` group (prefix `femtologging`),
alongside the existing permissive groups.
- Keep the current five-group behaviour for existing fixtures unchanged. Add the
variant behind an explicit selector rather than altering the default template.

Add the femtologging boundary fixture and wire tests:
- Create `tests/fixtures/architecture/femtologging_outside_logging_port/` with
`__init__.py`, a `logging.py` module that imports `femtologging` (the sanctioned
port, allowed), and an `api.py` module that imports `femtologging` directly
(must fail).
- Add the new fixture to the failing-case parametrize list in
`tests/test_architecture_enforcement.py`, asserting return code `1`, `ARCH001`,
the importer module, and `femtologging` in the diagnostic. This failing
assertion also guards against group shadowing, because a shadowed rule would
wrongly pass.
- Add a matching BDD scenario in
`tests/features/architecture_enforcement.feature` and a step binding in
`tests/steps/test_architecture_enforcement_steps.py`.
- Verify the production check still passes by running `make check-architecture`
after the config change.
===============================================================================

Task: 4

Implement Phase 4: add enforcement for the direct-call rule. The opaque handle
already makes a direct call a type error in the real tree, so add tests that
hold this gate.

Add a negative type-check fixture and test:
- Create a negative fixture outside the main `ty` scope that acquires a
`LoggerHandle` from the port and calls `.info(...)` on it directly.
- Add a test that runs `ty check` on that fixture path in isolation and asserts
a non-zero exit with an attribute or type error, mirroring the subprocess
pattern in `tests/test_architecture_enforcement.py`.
- Confirm the fixture is excluded from `make typecheck` so the standing type
check stays green.

Add a repo-local scanner test for the grep criterion:
- Add a test that globs `episodic/**/*.py`, excludes `episodic/logging.py`, and
asserts no attribute call matching `\.(debug|info|warning|error|critical|log)\(`
remains on a logger-bound name.
- Follow the `re.compile` plus `Path.read_text` idiom from
`tests/test_ci_workflow_contract.py`, or the `ast.parse` glob-and-walk idiom
from `scripts/tests/test_typos_rollout.py`.
- Keep the assertion set-based, and report every offending file, so a regression
names the exact site.
===============================================================================

Task: 5

Implement Phase 5: document the logging port and the enforcement rules in
`docs/developers-guide.md` so future cross-cutting logging changes have one
place to change.

Document the logging port contract:
- Update the `## Logging` section. Replace the current guidance that prefers
direct logger methods. State that call sites must obtain a `LoggerHandle` from
`get_logger` and emit through
`log_debug`/`log_info`/`log_warning`/`log_error`/`log_exception`.
- Document what a call site may assume, what the port guarantees to attach later
(the correlation identifier), and why the raw femtologging logger is not the
public surface.
- Style the new subsection like the existing `### Generation-run domain ports`
and `## Observability port abstractions` sections.

Document the architecture and call-site rules:
- Update the `### Architecture enforcement` section. Describe
`include_external_packages = true`, the new `logging_port`, `logging_backend`,
and `external_libraries` groups, and the first-match ordering that keeps
`femtologging` restricted.
- Record the direct-call rule and the two gates that enforce it: the opaque
handle under `ty` and the scanner test.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---