sales-trainer/docs/engineering-log/2026-08-15-s4-3-org-users-repositories.md

S4.3 — Organization/user repository packet

Date: 2026-08-15 Status: implementation and offline-dialect remediation complete locally; exact-current independent review passed; runtime cutover intentionally not started

Scope

• Added backend/app/repositories/contracts.py with OrganizationRepository and UserRepository Protocols.
• Added backend/app/repositories/sqlalchemy.py with SQLAlchemy adapters for organization/user CRUD and tenant-scoped user listing.
• Added backend/app/repositories/groups.py with tenant-scoped group/persona CRUD, org checks before persona creation, and controlled group updates.
• Added backend/app/repositories/sessions.py with tenant-scoped session/message reads and mutations; message sequence is explicit and database-unique.
• Added repository errors for missing entities and immutable/unknown update fields.
• Added backend/tests/test_repositories.py covering organization active filtering, updates, user auth-field preservation, tenant scope, duplicate-email rejection, and transaction ownership.
• Added backend/tests/test_group_repositories.py covering group/persona visibility, cross-org access denial, controlled updates, and cross-org persona-creation rejection.
• Added backend/tests/test_session_repositories.py covering session/message scope, one-shot uniqueness, message sequence uniqueness, and cross-org mutation denial.

Repositories flush but do not commit. The caller owns the transaction boundary so future services can atomically persist multiple aggregates. JSON stores remain authoritative; no route/factory cutover was made.

TDD evidence

• RED: repository contract test collection failed with ModuleNotFoundError: app.repositories before implementation.
• First GREEN attempt exposed SQLite timezone metadata normalization; the test now compares the instant after normalizing SQLite’s naive representation while PostgreSQL remains timezone-aware.
• Focused repository tests: 8 passed.
• Full backend suite after the cross-tenant lookup and offline-dialect remediations: 209 passed.
• Offline Alembic MySQL regression: RED before the shared validator; GREEN after test_alembic_offline_path_rejects_unsupported_dialects was added.

Verification

• python -m compileall -q app migrations tests: passed.
• git diff --check: passed.
• Repository added-line security scan: repository_added_line_findings=[].
• No production database, JSON store, credentials, deploy, or live service was touched.

Remaining gates

• Fresh exact-current reviewer deleg_40e8edf9 returned valid five-key JSON with passed=true, empty blocking arrays, and five non-blocking suggestions after deleg_c2e728d8 found and the local tree remediated an offline unsupported-dialect path. The prior valid reviewer deleg_cf56b7d3 correctly failed on the now-remediated unscoped UserRepository lookup.
• PostgreSQL execution and repository wiring are not verified.
• JSON importer, parity/count/hash comparison, rollback rehearsal, and runtime cutover remain blocked by later S4 packets.
• Do not delete JSON stores or switch production dependencies until those gates pass.

Independent review verdict

• deleg_40e8edf9 — valid exact-current review; passed=true; security_concerns=[]; logic_errors=[].
• Verified: keyword-only tenant scoping, non-disclosing cross-tenant reads, immutable auth-field handling, flush-only transaction ownership, tenant/uniqueness constraints, ORM/Alembic parity, SQLite/PostgreSQL partial-index rendering, and online/offline MySQL rejection before SQL rendering.
• Non-blocking suggestions: add explicit before-commit and immutable-field regression assertions, document global username/email uniqueness intent, map duplicate-key errors, and run live PostgreSQL smoke before cutover.