chore(authz): scrub internal project references from comments and docstrings (#268)

Scrubs internal references (Linear ticket IDs, internal service names,
internal flag names) from comments and docstrings across already-landed
authorization code. Fixes issues introduced by #248, #252, #255, #257,
#259, and #260.

No behavior changes.

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR is a pure housekeeping change that scrubs internal references —
Linear ticket IDs (e.g. `AGX1-263`, `AGX1-290`), internal service names
(`SpiceDB`, `Spark`, `agentex-auth`), and internal flag/PR references —
from comments and docstrings across 13 authorization-related source and
test files. No executable code is touched.

- Comments and docstrings across `port.py`, `authorization_service.py`,
`agent_api_keys.py`, and related utilities have internal service names
replaced with generic terms like \"authorization service\" or
\"authorization schema\".
- TODO comments in `agent_api_key_authorization.py`,
`agent_authorization.py`, and `authorization_shortcuts.py` have internal
ticket IDs stripped, with file-level context substituted where the
ticket reference previously identified the work location.
- Module docstrings in all six affected test files have ticket-prefixed
deliverable descriptions replaced with plain behavioral descriptions.

<details><summary><h3>Confidence Score: 5/5</h3></summary>

All changes are confined to comments and docstrings; no executable code
is modified.

Every diff hunk touches only comment text, docstrings, or module-level
strings. There are no logic, control-flow, or interface changes anywhere
in the PR, making regression risk essentially zero.

No files require special attention.
</details>

<h3>Important Files Changed</h3>

| Filename | Overview |
|----------|----------|
| agentex/src/adapters/authorization/port.py | Docstring-only: replaced
"SpiceDB" with "authorization" in register_resource docstring. |
| agentex/src/api/routes/agent_api_keys.py | Comment-only: removed
"SpiceDB" references from two inline comments in create/delete route
handlers. |
| agentex/src/domain/services/authorization_service.py | Docstring-only:
replaced "SpiceDB schema" with "authorization schema" in
register_resource docstring. |
| agentex/src/domain/use_cases/agent_api_keys_use_case.py |
Comment-only: removed unconditional-routing comment referencing internal
service names and ticket numbers; also cleaned docstring referencing
internal routing logic. |
| agentex/src/utils/agent_api_key_authorization.py | Comment-only:
replaced TODO(AGX1-290) with plain TODO, removing the Linear ticket
reference. |
| agentex/src/utils/agent_authorization.py | Comment-only: replaced
TODO(AGX1-290) with plain TODO, removing the Linear ticket reference. |
| agentex/src/utils/authorization_shortcuts.py | Comment-only: updated
TODO to reference the file name instead of internal ticket/PR numbers. |
|
agentex/tests/integration/services/test_agent_api_key_service_dual_write.py
| Docstring-only: removed references to "Spark AuthZ", internal ticket
numbers, and internal service names throughout module docstring and
inline comments. |
| agentex/tests/integration/services/test_schedule_service_dual_write.py
| Docstring-only: removed "Spark AuthZ" and "SpiceDB" references across
the module docstring and inline comments. |
|
agentex/tests/integration/api/checkpoints/test_checkpoints_authz_api.py
| Docstring-only: removed AGX1-302 ticket reference and internal
terminology from module docstring. |
| agentex/tests/integration/api/events/test_events_authz_api.py |
Docstring-only: replaced "AGX1-244" ticket reference in module docstring
with a plain description. |
| agentex/tests/integration/api/messages/test_messages_authz_api.py |
Docstring-only: removed AGX1-277 ticket reference from module docstring.
|
| agentex/tests/unit/api/test_agent_api_keys_authz.py | Docstring-only:
removed AGX1-263 ticket reference and "Spark AuthZ" mention from module
docstring. |

</details>

<details><summary><h3>Flowchart</h3></summary>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["PR #268: Scrub internal references"] --> B["Source files\n(port.py, agent_api_keys.py,\nauthorization_service.py,\nagent_api_keys_use_case.py,\n3 utils files)"]
    A --> C["Test files\n(6 integration + unit tests)"]
    B --> D["Replace: SpiceDB → authorization service/schema\nRemove: agentex-auth, Spark, internal PR refs\nStrip: AGX1-xxx ticket IDs from TODOs"]
    C --> E["Replace: AGX1-xxx deliverable labels → plain descriptions\nRemove: Spark AuthZ, scaleapi/agentex#353, etc."]
    D --> F["No executable code changed"]
    E --> F
```
</details>

<sub>Reviews (2): Last reviewed commit: ["chore(authz): scrub internal
project
ref..."](62581f7)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=35250665)</sub>

<!-- /greptile_comment -->

Author: asherfink

agentex/src/adapters/authorization/port.py

@@ -57,11 +57,11 @@ async def register_resource(
         resource: AgentexResource,
         parent: AgentexResource | None = None,
     ) -> None:
-        """Register a newly created resource in SpiceDB with the principal as
-        owner. Optionally writes a lifecycle parent edge.
+        """Register a newly created resource with the principal as owner.
+        Optionally writes a lifecycle parent edge.
 
         Use this on resource create instead of ``grant`` when the resource
-        type's SpiceDB definition has a parent relation that permission
+        type's authorization schema has a parent relation that permission
         checks cascade through (e.g. ``agent_api_key`` declares
         ``parent_agent``). Without writing that edge here the cascade fails
         closed.

agentex/src/api/routes/agent_api_keys.py

@@ -57,8 +57,8 @@ async def create_api_key(
         )
     agent = await agent_use_case.get(id=request.agent_id, name=request.agent_name)
 
-    # No api_key resource exists yet, so SpiceDB can't gate transitively —
-    # gate on parent ``agent.update`` directly.
+    # No api_key resource exists yet, so the authorization service can't gate
+    # transitively — gate on parent ``agent.update`` directly.
     await authorization_service.check(
         resource=AgentexResource.agent(agent.id),
         operation=AuthorizedOperationType.update,
@@ -211,8 +211,8 @@ async def delete_agent_api_key(
         param_name="id",
     ),
 ) -> str:
-    # SpiceDB's ``api_key.delete`` expands transitively to
-    # ``parent_agent->update``, so the dep above enforces both factors.
+    # ``api_key.delete`` expands transitively to ``parent_agent->update``,
+    # so the dep above enforces both factors.
     await agent_api_key_use_case.delete(id=id)
     return f"Agent API key with ID {id} deleted"
 

agentex/src/domain/services/authorization_service.py

@@ -197,7 +197,7 @@ async def register_resource(
     ) -> None:
         """Register a newly created resource with the principal as owner.
 
-        Prefer this over ``grant`` when the resource's SpiceDB schema has
+        Prefer this over ``grant`` when the resource's authorization schema has
         a parent relation that permissions cascade through (e.g.
         ``agent_api_key`` declares ``parent_agent``). Pass ``parent`` to
         link the child to its parent atomically; without it the cascade

agentex/src/domain/use_cases/agent_api_keys_use_case.py

@@ -90,8 +90,6 @@ async def create(
 
         api_key_id = orm_id()
 
-        # Unconditional — agentex-auth decides per-account whether the call
-        # routes to Spark or the legacy backend.
         await self._register_api_key_in_auth(
             api_key_id=api_key_id,
             agent_id=agent.id,
@@ -157,9 +155,8 @@ async def _deregister_api_key_from_auth(self, *, api_key_id: str) -> None:
 
         ``deregister_resource`` removes the resource and all of its
         relationships (owner, parent, grantees) atomically. Always invoked;
-        agentex-auth's per-account routing (#353) decides whether the call
-        targets Spark or the legacy backend. Failures are logged but do not
-        block the delete.
+        the authorization service decides how to route the call. Failures are
+        logged but do not block the delete.
         """
         try:
             await self.authorization_service.deregister_resource(
@@ -252,7 +249,7 @@ async def list(
         page_number: int,
         id: list[str] | None = None,
     ) -> list[AgentAPIKeyEntity]:
-        # ``id`` is the FGAC-filter shape used by route deps (DAuthorizedResourceIds).
+        # ``id`` is the authorization-filter shape used by route deps (DAuthorizedResourceIds).
         # ``None`` means "no filter" (e.g. authz bypass); an empty list means
         # "caller can see no api_keys" and must short-circuit to avoid the
         # base repo translating ``id=[]`` into an unfiltered query.

agentex/src/utils/agent_api_key_authorization.py

@@ -18,7 +18,7 @@ async def _check_api_key_or_collapse_to_404(
     """Check an api_key resource; collapse any denial to 404 to avoid leaking
     cross-tenant existence. Mirrors ``_check_task_or_collapse_to_404``.
 
-    TODO(AGX1-290): restore the 403/404 split once api_keys carry tenant scope.
+    TODO: Restore the 403/404 split once api_keys carry tenant scope.
     """
     try:
         await authorization.check(

agentex/src/utils/agent_authorization.py

@@ -15,7 +15,7 @@ async def check_agent_or_collapse_to_404(
     cross-tenant existence. Mirrors ``check_task_or_collapse_to_404`` in
     ``task_authorization.py`` — see that docstring for the full rationale.
 
-    TODO(AGX1-290): restore 403/404 split once agents carry tenant scope.
+    TODO: Restore the 403/404 split once agents carry tenant scope.
     """
     try:
         await authorization.check(

agentex/tests/integration/api/checkpoints/test_checkpoints_authz_api.py

@@ -1,17 +1,15 @@
 """
 Integration tests for checkpoint-route authorization.
 
-Covers the AGX1-302 deliverable: checkpoint routes have no SpiceDB type of
-their own. Each route enforces on the owning task (``thread_id`` is the task id)
-via ``DAuthorizedBodyId(task, ...)``:
+Checkpoint routes have no authorization type of their own. Each route enforces
+on the owning task (``thread_id`` is the task id) via ``DAuthorizedBodyId(task, ...)``:
 
 * get-tuple / list -> ``task.read`` (view).
 * put / put-writes -> ``task.update`` (editor + owner); delete-thread -> ``task.delete``.
 
-Per the canonical ``DAuthorizedBodyId`` task wrap (the 404/403 collapse landed
-by AGX1-275 / #249), a denied check on the parent task collapses to 404 (not
-403) on every route — reads and writes alike — so callers cannot probe
-cross-tenant existence by comparing response codes.
+Per the canonical ``DAuthorizedBodyId`` task wrap, a denied check on the parent
+task collapses to 404 (not 403) on every route — reads and writes alike — so
+callers cannot probe cross-tenant existence by comparing response codes.
 """
 
 from typing import Any

agentex/tests/integration/api/events/test_events_authz_api.py

@@ -1,4 +1,4 @@
-"""AGX1-244: event routes delegate authz to the parent agent."""
+"""Tests for event route authorization — routes delegate checks to the parent agent."""
 
 from typing import Any
 from unittest.mock import patch

agentex/tests/integration/api/messages/test_messages_authz_api.py

@@ -1,9 +1,9 @@
 """
 Integration tests for message-route authorization.
 
-Covers the AGX1-277 deliverable: list/get messages enforce ``task.read`` on
-the parent task, with denied checks collapsing to 404 (not 403) so callers
-cannot probe cross-tenant existence by comparing response codes.
+List/get message routes enforce ``task.read`` on the parent task, with denied
+checks collapsing to 404 (not 403) so callers cannot probe cross-tenant
+existence by comparing response codes.
 """
 
 from typing import Any

agentex/tests/integration/services/test_agent_api_key_service_dual_write.py

@@ -1,25 +1,25 @@
-"""Integration tests for AgentAPIKeysUseCase dual-write to Spark AuthZ.
+"""Integration tests for AgentAPIKeysUseCase dual-write to the authorization service.
 
-These cover the AGX1-272 dual-write path. scale-agentex calls
-``register_resource`` / ``deregister_resource`` unconditionally; per-account
-routing (Spark vs legacy SGP) is owned by agentex-auth (scaleapi/agentex#353)
-so scale-agentex does NOT couple to egp-api-backend's feature-flag service.
+scale-agentex calls ``register_resource`` / ``deregister_resource``
+unconditionally; per-account routing is owned by the authorization gateway,
+so scale-agentex does NOT couple to the authorization flag service.
 
 - Create calls register_resource with parent=agent (the parent_agent edge
-  is load-bearing for the SpiceDB cascade).
+  is load-bearing for the authorization cascade).
 - Delete calls deregister_resource after the Postgres row is gone.
-- Spark failure prevents row: when register_resource raises, the api_key
-  is NOT persisted.
+- Registration failure prevents row: when register_resource raises, the
+  api_key is NOT persisted.
 - Deregister failure does not block delete: when deregister_resource
   raises, the DB delete still completes and the failure is logged.
 - No creator → no register: if neither user_id nor service_account_id is
   resolvable, the dual-write is a no-op (logged) and the row still lands.
 
 The tests intentionally mock the repository, authorization service, agent
 repository, and HTTP client. The behaviour under test is the call sequencing
-inside ``AgentAPIKeysUseCase`` — not Postgres or Spark itself.
+inside ``AgentAPIKeysUseCase`` — not the underlying persistence or authorization
+cluster itself.
 
-Note on structural divergence from the task PR (AGX1-274): tasks live behind
+Note on structural divergence from the task dual-write: tasks live behind
 ``AgentTaskService``; agent_api_keys have no service layer, so the dual-write
 logic is colocated in ``AgentAPIKeysUseCase``.
 """
@@ -154,7 +154,7 @@ async def test_create_api_key_calls_register_resource_with_parent(
     registered_resource: AgentexResource = register.await_args.kwargs["resource"]
     assert registered_resource.type == AgentexResourceType.api_key
     assert registered_resource.selector == api_key.id
-    # parent_agent edge is load-bearing — without it the SpiceDB cascade
+    # parent_agent edge is load-bearing — without it the authorization cascade
     # `read = ... & parent_agent->read & ...` fails closed for every reader.
     registered_parent: AgentexResource = register.await_args.kwargs["parent"]
     assert registered_parent is not None