Decorator-level DI guards read as unguarded: Depends() in a decorator emits no DEPENDS_ON

[zaebee]

Found by an independent review of #428 (which fixed the module-level and class-body halves of #416).

The gap

_walk returns as soon as it sees a decorated_definition, handing the node to _handle_decorated_definition. That method descends into the definition's grandchildren and never into the decorator nodes themselves. So any call written inside a decorator expression produces no edge at all — on a function, a method, a class, or a nested class.

@deco(Foo())          # the Foo() call is invisible
def f(): ...

Verified absent both before and after #428.

Why it matters concretely

owner-api, app/domains/admin/system.py:

@router.post("/showcase/reset", dependencies=[Depends(get_current_active_superuser)])
async def trigger_showcase_reset(...):

trigger_showcase_reset has no DEPENDS_ON edge. cgis audit (see audit.py) reads DEPENDS_ON as the evidence that an endpoint is guarded, so this endpoint audits as unguarded when it is in fact superuser-only. Any route that declares its guard at the decorator rather than in the signature has the same false negative.

Not simply "walk the decorators too"

The CALLS half is mechanical. The DI half is a design question, which is why it is a separate issue rather than a line in #428:

• Depends(get_current_active_superuser) inside @router.post(...) is lexically at module level but semantically guards the decorated function. Attributing it to the module would be honest about location and useless for the audit; attributing it to the function is what the audit wants, and is the first place in the extractor where an edge's source is not its lexical owner.
• 2026-06-11-fastapi-di-edges-design.md §6 puts class-body DI aliases out of scope. Decorator DI is not that case, but the spec does not say what it is either — it needs a decision written down before code.

Suggested shape

1. Walk decorator expressions for CALLS, sourced at the decorated definition (it is the nearest owner, and a decorator has no other).
2. Decide, and record in the DI spec, whether Depends/Security in a decorator emits DEPENDS_ON sourced at the decorated function. Measure the audit's false-negative count on owner-api both ways before choosing.
3. Re-run the audit false-negative count as the acceptance number.

[zaebee]

Measured while implementing the CALLS half (#434). Two corrections to this issue's own claims, one of which is mine.

The "117 names in owner-api decorators" figure was measured on a stale tree

That count came from a checkout at b6904d69 (#1338). owner-api main is at 70c679b6, fourteen-plus merges ahead — services/factory.py deleted in #1342, api/dependencies/grpc/ moved to app/gen in #1350, several schemas deleted in #1352. Re-measured on the current ref.

The orphan-query motivation does not reproduce

With decorator arguments walked, on 70c679b6:

edges       73604 → 74356  (+752)
REFERENCES   6932 →  7081  (+149)
orphans        19 →    19  (rescued 0, new 0)

One class gained a production reference and it already had others. The reason is structural rather than incidental: a FastAPI handler that declares response_model=Schema almost always annotates -> Schema as well, so the decorator is redundant evidence, not sole evidence. Same on cgis: 2 → 2.

So the orphan-precision argument in this issue is weaker than it reads. What walking decorators buys the orphan query is insurance for the case where the decorator really is the only mention, not a current rescue.

What did reproduce, and one thing this issue did not predict

The edges themselves are real — @app.route(build()) genuinely calls build. And a second gap turned up while fixing the first:

A decorated class recorded no decorator at all. process_function_node emits one CALLS edge per decorator name; process_class_node is handed the same list and emitted none. @register above a class was a use nothing wrote down, while the same decorator above a function was recorded. On owner-api that is 353 classes, 0 → 359 edges. That asymmetry is the more valuable half of #434.

What is still open here

The DI half — the gap that opened this issue. @router.post(..., dependencies=[Depends(get_current_active_superuser)]) still leaves trigger_showcase_reset with no DEPENDS_ON, so cgis audit still reads a superuser-only endpoint as unguarded.

#434 deliberately does not touch it, and pins a test that the decorator path emits no DEPENDS_ON, so changing that has to be a decision rather than a side effect. The decision needed:

May an edge's source differ from its lexical owner?

Depends(guard) inside @router.post(...) sits at module level and guards the decorated function. Attributing it to the module is honest about location and useless to the audit; attributing it to the function is what the audit wants and is the first such case in the extractor. 2026-06-11-fastapi-di-edges-design.md §6 rules class-body DI aliases out of scope and says nothing about decorators.

Suggested next step: write that decision into the DI spec, with the audit's false-negative count on owner-api measured both ways as the acceptance number — not an edge count.

[zaebee]

The CALLS half shipped in #434 (fd0c63f); this issue now tracks the DI half only. Retitled accordingly — the original title's first clause ("calls inside a decorator expression are dropped") is no longer true.

What shipped

_walk_decorators walks a decorator's expression, attributing calls and name references to the decorated definition. It skips the decorator's head — the leftmost primary, which process_function_node already records — and walks everything else, so @a.b(X)(Y), @registry[X] and @(deco(X)) are covered along with the ordinary @router.post(..., response_model=Schema). A second gap turned up while fixing the first: a decorated class recorded no decorator at all, where a decorated function did — 353 classes on owner-api.

Measured on owner-api at 70c679b6, same input tree with both extractors: +752 edges, +359 decorator edges on classes, and +21 distinct new reference facts (of +149 rows — 128 duplicated a pair the return annotation already had). Zero orphans rescued, as recorded above.

What remains, and the decision it needs

@router.post("/showcase/reset", dependencies=[Depends(get_current_active_superuser)]) still leaves trigger_showcase_reset with no DEPENDS_ON, so cgis audit still reads a superuser-only endpoint as unguarded. That is the gap this issue was filed for.

#434 deliberately did not touch it and pins a test that the decorator path emits no DEPENDS_ON — verified by review across Depends(guard), Security(guard, scopes=[...]), Depends(dependency=guard) and Annotated[Schema, Depends(guard)] in decorator arguments, all of which yield a CALLS and nothing else. So changing it has to be a decision rather than a side effect.

The decision:

May an edge's source differ from its lexical owner?

Depends(guard) inside @router.post(...) sits at module level and guards the decorated function. Attributing it to the module is honest about location and useless to the audit; attributing it to the function is what the audit wants, and would be the first such case in the extractor. 2026-06-11-fastapi-di-edges-design.md §6 rules class-body DI aliases out of scope and says nothing about decorators.

Acceptance number should be the audit's false-negative count on owner-api, measured both ways — not an edge count. Count the endpoints that are guarded in source but read as gaps today, and again after.

[zaebee]

Population measured, and it changes how this should be prioritised. On Ownima/owner-api at b7d02fe6, outside tests:

guards declared in a route DECORATOR (dependencies=[Depends(...)])     1
guards declared in the SIGNATURE (CurrentAdminDep, = Depends(...))   238

The one is domains/admin/system.py:30 — the example this issue was written from. So it is not "any route that declares its guard at the decorator" as a class of routes; on the repository we can measure, that example is the entire population.

That does not make the gap unreal — cgis audit reads a superuser-only endpoint as unguarded, and that is a wrong answer in a security-adjacent report. But the cost side is unchanged: it needs a written decision on whether an edge's source may differ from its lexical owner, which is the first such case in the extractor and an architectural commitment. One endpoint of evidence is thin ground for making it.

Two things would change the calculus, and either is cheap to check before starting:

• another repository in the dogfooding set where the decorator form is common (the FastAPI convention differs by codebase — some teams put every guard in dependencies=[]);
• a second consumer of DEPENDS_ON beyond audit, which would raise the cost of it being incomplete.

Recorded here so the next reader does not re-derive it.