kite/.planning/phases/03-document-migration-multi-user-isolation/03-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	requirements-completed	duration	completed
03-document-migration-multi-user-isolation	01	testing, database	pytest alembic sqlite minio xfail fixtures migration	phase provides 02-users-authentication services.auth.create_access_token, hash_password, User/Quota ORM models	19 xfail(strict=False) Wave 0 test stubs covering all Phase 3 requirements auth_user and admin_user pytest fixtures issuing valid JWTs with Quota rows mock_minio_presigned and mock_minio_stat fixtures (raising=False, pre-Plan 03-02) Alembic migration 0003: null-user doc cleanup + NOT NULL + topic cleanup + quota reconcile + ix_topics_user_id	03-02-PLAN 03-03-PLAN 03-04-PLAN	added patterns xfail(strict=False) Wave 0 stubs as executable test scaffolding for future plans monkeypatch.setattr with raising=False for patching not-yet-existing methods batch_alter_table for SQLite-compatible ALTER COLUMN in Alembic migrations MinIO step in migration gated on MINIO_ENDPOINT env var for SQLite test safety Deferred Minio import inside upgrade() — avoids import at downgrade/test time	created modified backend/tests/test_quota.py (4 xfail stubs: STORE-03, STORE-05, STORE-06, SC2) backend/migrations/versions/0003_multi_user_isolation.py (revision='0003') backend/tests/conftest.py (auth_user, admin_user, mock_minio_presigned, mock_minio_stat) backend/tests/test_alembic.py (test_migration_0003 appended) backend/tests/test_classifier.py (3 xfail stubs: DOC-03, DOC-05, D-15) backend/tests/test_documents.py (6 xfail stubs: D-05, STORE-04, SEC-04, D-16) backend/tests/test_topics.py (4 xfail stubs: DOC-04, D-09, D-17) backend/tests/test_settings.py (1 xfail stub: D-12)	batch_alter_table used for documents.user_id NOT NULL — required for SQLite test compat, transparent passthrough on PostgreSQL MinIO step in migration gated on MINIO_ENDPOINT presence — migration runs safely in CI without live MinIO Minio import deferred inside upgrade() body — avoids import overhead at downgrade() or test collection time raising=False on mock_minio_presigned and mock_minio_stat — patches install before methods exist (Plan 03-02) pytest import added to test_topics.py — pre-existing file was missing it	STORE-03 STORE-04 STORE-05 STORE-06 SEC-04 DOC-03 DOC-04 DOC-05	5min	2026-05-23

Phase 3 Plan 01: Multi-User Isolation Wave 0 Summary

Alembic migration 0003 (null-user cleanup + NOT NULL + topic purge + quota reconcile) and 19 pytest xfail stubs with auth_user/admin_user/MinIO mock fixtures as Phase 3 Wave 0 scaffolding

Performance

• Duration: 5 min
• Started: 2026-05-23T11:39:25Z
• Completed: 2026-05-23T11:45:14Z
• Tasks: 2
• Files modified: 8

Accomplishments

• Created 0003_multi_user_isolation.py migration: collects null-user object_keys, deletes document_topics + documents (null user_id), removes MinIO objects (gated on MINIO_ENDPOINT), deletes all topics, alters documents.user_id to NOT NULL via batch_alter_table, creates ix_topics_user_id, reconciles quotas.used_bytes from SUM(size_bytes)
• Added auth_user, admin_user, mock_minio_presigned, mock_minio_stat shared fixtures to conftest.py — all later plans depend on these
• Created or appended 19 xfail(strict=False) Wave 0 test stubs covering all Phase 3 requirements across 6 test files

New Test IDs

All 19 new test IDs are collectable with --collect-only:

Test ID	File	Requirement	Target Plan
test_quota_increment_atomic	test_quota.py	STORE-03	03-02
test_concurrent_quota_race	test_quota.py	STORE-03 SC2	03-02
test_quota_exceeded_response	test_quota.py	STORE-05	03-02
test_delete_decrements_quota	test_quota.py	STORE-06	03-02
test_migration_0003	test_alembic.py	D-01, D-02, D-03, D-10	03-01
test_per_user_provider	test_classifier.py	DOC-03	03-04
test_celery_task_uses_user_provider	test_classifier.py	DOC-05	03-04
test_default_provider_fallback	test_classifier.py	D-15	03-04
test_upload_url_endpoint	test_documents.py	D-05	03-02
test_confirm_endpoint	test_documents.py	D-05, STORE-03	03-02
test_get_quota	test_documents.py	STORE-04	03-02
test_cross_user_access_404	test_documents.py	SEC-04	03-03
test_admin_cannot_access_documents	test_documents.py	SEC-04 SC4	03-03
test_documents_require_auth	test_documents.py	D-16	03-02
test_topic_namespace	test_topics.py	DOC-04	03-03
test_admin_create_system_topic	test_topics.py	D-09	03-03
test_regular_user_cannot_create_system_topic	test_topics.py	D-09	03-03
test_topics_require_auth	test_topics.py	D-17	03-03
test_settings_endpoint_removed	test_settings.py	D-12	03-04

Task Commits

1. Task 1: Create Wave 0 test scaffolds and shared fixtures - 21ec9cb (test)
2. Task 2: Write Alembic migration 0003 - 807a1b3 (feat)

Files Created/Modified

• backend/tests/test_quota.py — NEW; 4 xfail stubs for atomic quota enforcement (STORE-03/05/06, SC2)
• backend/migrations/versions/0003_multi_user_isolation.py — NEW; Alembic migration revision "0003"
• backend/tests/conftest.py — Added auth_user, admin_user, mock_minio_presigned, mock_minio_stat fixtures
• backend/tests/test_alembic.py — Appended test_migration_0003 with full pre-seed + post-migration assertions
• backend/tests/test_classifier.py — Appended 3 xfail stubs (DOC-03, DOC-05, D-15)
• backend/tests/test_documents.py — Appended 6 xfail stubs (D-05, STORE-04, SEC-04, D-16)
• backend/tests/test_topics.py — Appended 4 xfail stubs (DOC-04, D-09, D-17) + added import pytest
• backend/tests/test_settings.py — Appended test_settings_endpoint_removed stub (D-12)

Decisions Made

• batch_alter_table for NOT NULL constraint: SQLite requires batch_alter_table for ALTER COLUMN. PostgreSQL ignores the batch wrapper transparently. This is a downstream constraint for anyone testing the migration against SQLite in CI — the test suite uses it.
• MinIO gated on env var: if os.environ.get("MINIO_ENDPOINT"): before the MinIO step ensures migration runs safely in CI/SQLite environments without a live MinIO server. The MinIO import is also deferred inside upgrade() to avoid importing at collection time.
• raising=False for mock fixtures: The mock_minio_presigned and mock_minio_stat fixtures patch MinIOBackend.generate_presigned_put_url and MinIOBackend.stat_object which don't exist until Plan 03-02. The raising=False flag ensures the patch succeeds when the attribute is absent.
• pytest import added to test_topics.py: The file was missing import pytest which was required once the xfail decorators were appended (Rule 1 - auto-fix).

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] Missing import pytest in test_topics.py

• Found during: Task 1 acceptance criteria verification
• Issue: test_topics.py had no import pytest — the new @pytest.mark.xfail decorators caused a NameError: name 'pytest' is not defined collection error
• Fix: Added import pytest to test_topics.py header
• Files modified: backend/tests/test_topics.py
• Verification: pytest --collect-only returned all 19 test IDs with no errors
• Committed in: 21ec9cb (Task 1 commit)

---

Total deviations: 1 auto-fixed (Rule 1 - Bug) Impact on plan: Minor fix necessary for test collection. No scope creep.

Issues Encountered

Pre-existing MinIO-dependent tests (test_upload_txt_no_classify, etc.) fail locally because no MinIO server is running at minio:9000. These failures predate this plan and are out-of-scope per the scope boundary rule. They were failing before any changes were made.

Threat Surface Scan

No new network endpoints, auth paths, file access patterns, or schema changes at trust boundaries introduced by this plan beyond those defined in the threat model. The migration executes as a one-time data cleanup operation with documented behavior.

Known Stubs

All xfail stubs use assert True as placeholders — this is intentional for Wave 0 scaffolding. Each stub's docstring documents which plan will implement it. None of the stubs prevent the plan's goal (Wave 0 scaffolding) from being achieved.

Next Phase Readiness

Ready for Plan 03-02: presigned upload flow backend + auth guards. The auth_user, admin_user, mock_minio_presigned, and mock_minio_stat fixtures are in place. The migration 0003 is written and will apply the NOT NULL constraint when run against PostgreSQL.

---

Phase: 03-document-migration-multi-user-isolation Completed: 2026-05-23

Self-Check: PASSED

• backend/tests/test_quota.py exists on disk
• backend/migrations/versions/0003_multi_user_isolation.py exists on disk
• backend/tests/conftest.py modified with 4 new fixtures
• Commit 21ec9cb exists (Task 1)
• Commit 807a1b3 exists (Task 2)
• All 19 new test IDs collected by pytest
• revision = "0003" present in migration file
• down_revision = "0002" present in migration file
• DELETE FROM topics present in migration file
• ix_topics_user_id present in migration file
• SUM(size_bytes) present in migration file
• nullable=False present in migration file