feat(api.iam): AIHCM-143 workspace repo infra

[jsell-rh]

Summary by CodeRabbit

• New Features
  • Workspace management: persistent workspace entities, repository with CRUD and outbox event support, and observability probes.
  • Configurable default workspace name (falls back to tenant name).
• Migrations
  • Added migration to create workspaces table and a migration to change group tenant FK to RESTRICT.
• Tests
  • Added comprehensive unit test suite covering workspace repository behavior and event emission.

[coderabbitai]

Walkthrough

This PR adds workspace support to the IAM bounded context. It introduces new SQLAlchemy ORM model files (WorkspaceModel, TenantModel, GroupModel, UserModel, APIKeyModel) and a models package export; an Alembic migration to create the workspaces table and a migration to change groups FK behavior; a PostgreSQL-backed WorkspaceRepository that uses a transactional outbox to persist domain events; observability probes for workspace repository operations; a FastAPI dependency factory get_workspace_repository; an IAM settings field default_workspace_name; and comprehensive unit tests for the WorkspaceRepository.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Client
participant WorkspaceRepo as WorkspaceRepository
participant DB as AsyncSession (Postgres)
participant Outbox as OutboxRepository
participant Probe as WorkspaceRepositoryProbe
participant Serializer as IAMEventSerializer

Client->>WorkspaceRepo: save(workspace)
WorkspaceRepo->>DB: upsert WorkspaceModel (within transaction)
WorkspaceRepo->>Serializer: serialize(workspace.events)
WorkspaceRepo->>Outbox: append(serialized events) (same transaction)
WorkspaceRepo->>DB: flush/commit
DB-->>WorkspaceRepo: commit success
WorkspaceRepo->>Probe: workspace_saved(workspace.id, tenant_id)
WorkspaceRepo-->>Client: return

mermaid
sequenceDiagram
participant Client
participant WorkspaceRepo as WorkspaceRepository
participant DB as AsyncSession (Postgres)
participant Probe as WorkspaceRepositoryProbe

Client->>WorkspaceRepo: get_by_id(id)
WorkspaceRepo->>DB: query WorkspaceModel by id
DB-->>WorkspaceRepo: model | none
alt model found
WorkspaceRepo->>Probe: workspace_retrieved(id)
WorkspaceRepo-->>Client: Workspace domain object
else not found
WorkspaceRepo->>Probe: workspace_not_found(id=id)
WorkspaceRepo-->>Client: None
end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(api.iam): create workspace domain objects #200: Adds the Workspace aggregate and WorkspaceCreated/WorkspaceDeleted events that the new WorkspaceRepository persists via the outbox.
• feat(outbox): implement transactional outbox pattern for SpiceDB consistency #106: Implements the transactional outbox infrastructure (OutboxRepository, serializers) that WorkspaceRepository depends on.
• refactor(api.iam): bind tenant scope at the service dependency level #173: Adds FastAPI dependency wiring patterns similar to the new get_workspace_repository factory and related DI changes.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: introducing workspace repository infrastructure for the IAM module, with appropriate conventional commit format and ticket reference.
Docstring Coverage	✅ Passed	Docstring coverage is 98.67% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch jsell/feat/AIHCM-143-workspace-repo-infra

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-02-06 21:37 UTC

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/api/iam/infrastructure/models/workspace.py`:
- Around line 49-54: WorkspaceModel currently redefines created_at and
updated_at, which strips TimestampMixin's insert_default and onupdate behavior;
remove the created_at and updated_at mapped_column overrides from WorkspaceModel
so it inherits the mixin's timestamp defaults and callbacks (refer to
WorkspaceModel, created_at, updated_at, and
TimestampMixin/insert_default/onupdate) to restore consistent automatic
timestamp population like TenantModel and UserModel.

In `@src/api/iam/infrastructure/observability/repository_probe.py`:
- Around line 314-318: Update the module-level docstring to mention workspaces
in addition to groups, users, and tenants so it accurately reflects the new
WorkspaceRepositoryProbe; revise the top-level description to state that the
module covers group/user/tenant/workspace repository operations and that it
records domain events during workspace persistence operations (aligning with the
existing WorkspaceRepositoryProbe class and related probe implementations).

🧹 Nitpick comments (2)

src/api/tests/unit/iam/infrastructure/test_workspace_repository.py (1)

652-664: Consider avoiding direct access to private attribute _serializer.

The test accesses repository._serializer (line 664), which is an implementation detail. This couples the test to the internal structure of WorkspaceRepository.

Consider verifying the default serializer behavior indirectly, such as by checking that serialization produces expected output when saving a workspace, rather than inspecting the private attribute.

♻️ Alternative approach

     def test_uses_default_serializer_when_not_injected(
-        self, mock_session, mock_outbox, mock_probe
+        self, mock_session, mock_outbox, mock_probe, tenant_id
     ):
-        """Should create default serializer when not injected."""
-        from iam.infrastructure.outbox import IAMEventSerializer
-
+        """Should use default serializer behavior when not injected."""
         repository = WorkspaceRepository(
             session=mock_session,
             outbox=mock_outbox,
             probe=mock_probe,
         )
 
-        assert isinstance(repository._serializer, IAMEventSerializer)
+        workspace = Workspace.create_root(name="Test", tenant_id=tenant_id)
+
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        # Save should succeed with default serializer
+        # (would fail if serializer was None or broken)
+        await repository.save(workspace)
+        mock_outbox.append.assert_called_once()

src/api/iam/infrastructure/workspace_repository.py (1)

144-189: Consider probe consistency for not-found cases.

get_by_id calls probe.workspace_not_found() when the workspace doesn't exist, but get_by_name and get_root_workspace silently return None. This inconsistency may be intentional (these methods are often used for existence checks where not-found is expected), but worth confirming the observability requirements.