C2(authentik-source-build): plan add python314-nixpkgs-compat prerequisite

During initial attempt to build authentik-django on ringtail, discovered
that nixos-25.11's python314 package set has two compat gaps: astor 0.8.1
fails its test suite (uses ast.Num/ast.Str removed in 3.14), and django
defaults to 4.2.x (which doesn't support 3.14). New card documents the
issue and the fix (carry the same overrides nixpkgs uses upstream).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/how-to/authentik/authentik-python-backend-derivation.md

@@ -4,6 +4,7 @@ modified: 2026-02-28
 status: active
 requires:
   - mirror-authentik-build-deps
+  - python314-nixpkgs-compat
 tags:
   - how-to
   - authentik
@@ -19,9 +20,10 @@ Build `authentik-django` — the Python/Django application that forms the core b
 This is the most complex component. The nixpkgs derivation uses `python3.override` with extensive `packageOverrides` to handle authentik's non-standard dependencies:
 
 - **4 in-tree Python packages** built from the monorepo: `ak-guardian`, `django-channels-postgres`, `django-dramatiq-postgres`, `django-postgres-cache`
-- **Forked `djangorestframework`** from `authentik-community/django-rest-framework` (specific commit)
+- **Standard `djangorestframework`** 3.16.1 from PyPI (no longer forked as of 2026.2.0 — the nixpkgs 2025.12.4 reference still uses the fork, but `[tool.uv.sources]` no longer overrides it)
 - **Pinned `dramatiq`** at 1.17.1 (upstream uses newer versions that break authentik)
-- **Django 5** forced via `django_5`
+- **Django 5** forced via `django_5` (see [[python314-nixpkgs-compat]])
+- **Python 3.14** required (`requires-python = "==3.14.*"`) — needs nixpkgs compat overrides (see [[python314-nixpkgs-compat]])
 - **60+ Python dependencies** from nixpkgs
 
 Post-install, the derivation patches hardcoded paths in `settings.py`, `default.yml`, `email/utils.py`, and `files/backends/file.py` to reference Nix store paths.
@@ -29,11 +31,12 @@ Post-install, the derivation patches hardcoded paths in `settings.py`, `default.
 ## What to Do
 
 1. Create a Python package override set that builds the 4 in-tree packages from source
-2. Pin the forked `djangorestframework` and `dramatiq` versions
-3. Build `authentik-django` using `hatchling` as the build backend
-4. Apply the 4 `substituteInPlace` patches for Nix store path references
-5. Copy lifecycle scripts, `manage.py`, blueprints, and web assets into the output
-6. Verify: `python -c "import authentik"` succeeds
+2. Include compat overrides from [[python314-nixpkgs-compat]] (`django_5`, `astor`)
+3. Pin `dramatiq` to 1.17.1 (standard `djangorestframework` 3.16.1 from nixpkgs — no longer forked)
+4. Build `authentik-django` using `hatchling` as the build backend
+5. Apply the 4 `substituteInPlace` patches for Nix store path references
+6. Copy lifecycle scripts, `manage.py`, blueprints, and web assets into the output
+7. Verify: `python -c "import authentik"` succeeds
 
 ## Key Details
 

docs/how-to/authentik/python314-nixpkgs-compat.md

@@ -0,0 +1,68 @@
+---
+title: Python 3.14 Nixpkgs Compatibility Overrides
+modified: 2026-02-28
+status: active
+requires:
+  - mirror-authentik-build-deps
+tags:
+  - how-to
+  - authentik
+  - nix
+---
+
+# Python 3.14 Nixpkgs Compatibility Overrides
+
+Document and implement the `packageOverrides` needed to build authentik's Python dependency tree under `python314` on nixos-25.11.
+
+## Problem
+
+Authentik 2026.2.0 requires Python 3.14 (`requires-python = "==3.14.*"`). The nixos-25.11 channel's `python314` package set has two issues:
+
+1. **`astor` 0.8.1** — test suite uses `ast.Num`, `ast.Str`, and `ast.NameConstant`, which were removed in Python 3.14. Build fails during `pytestCheckPhase`.
+2. **`django` defaults to 4.2.x** — Django 4.2 does not support Python 3.14. The `python314.pkgs.django` attribute points to `django_4` (4.2.28), not `django_5`.
+
+Both failures cascade through the dependency graph, breaking `trio` → `anyio` → `httpcore`/`azure-core`/etc. and ultimately `authentik-django`.
+
+## Research Findings
+
+### astor
+
+Current nixpkgs (unstable/newer 25.11 snapshots) already fixes this:
+
+- Uses an **unstable git snapshot** `df09001112f079db54e7c5358fa143e1e63e74c4` (2024-03-30), not the 0.8.1 release
+- Carries `python314-compat.patch` from upstream PR [#233](https://github.com/berkerpeksag/astor/pull/233)
+- The patch replaces removed `ast.Num`/`ast.Str`/`ast.NameConstant` with `ast.Constant` and guards affected tests with version checks
+- Hash: `sha256-VF+harl/q2yRU2yqN1Txud3YBNSeedQNw2SZNYQFsno=`
+
+Ringtail's nixos-25.11 registry pin predates this fix. Rather than updating the system-wide nixpkgs (which has broader implications), we carry the override in our derivation.
+
+### django
+
+The nixpkgs authentik `package.nix` (2025.12.4) includes `django = final.django_5;` in its `packageOverrides`. This is still needed for 2026.2.0 — `python314` does not default to Django 5.x.
+
+### Dependency chain (astor failure cascade)
+
+```
+astor (test failure)
+├── trio (nativeCheckInputs)
+│   └── anyio
+│       ├── httpcore → httpx → msgraph-sdk, azure-core, ...
+│       └── azure-core → azure-identity, azure-storage-blob
+├── djangoql (runtime dep of authentik)
+└── django 4.2.28 (also broken, separate issue)
+    └── authentik-django (1 dependency failed)
+```
+
+## What to Do
+
+Add these overrides to `authentik-django.nix`'s `packageOverrides` block:
+
+1. **`django = final.django_5;`** — same as nixpkgs authentik does
+2. **`astor`** — override to use the patched git snapshot with the python314-compat.patch, matching what current nixpkgs does (NOT just disabling tests)
+
+The override for astor should use `fetchFromGitHub` with owner `berkerpeksag`, repo `astor`, rev `df09001112f079db54e7c5358fa143e1e63e74c4`, and carry the patch from nixpkgs PR #233. This is a proper fix, not a test skip.
+
+## Related
+
+- [[authentik-python-backend-derivation]] — Parent card (depends on this)
+- [[build-authentik-from-source]] — Root goal

docs/how-to/how-to.md

@@ -103,6 +103,7 @@ Mikado chain for building Authentik from a custom Nix derivation (from source).
 - [[build-authentik-from-source]]
 - [[mirror-authentik-build-deps]]
 - [[authentik-api-client-generation]]
+- [[python314-nixpkgs-compat]]
 - [[authentik-python-backend-derivation]]
 - [[authentik-web-ui-derivation]]
 - [[authentik-go-server-derivation]]