feat(api.iam): create workspace domain objects

[jsell-rh]

Summary by CodeRabbit

• New Features

  • Workspace management: create/delete workspaces with parent/child hierarchy and explicit root workspace support; emits workspace lifecycle events.

• Infrastructure

  • Consolidated domain event surface and improved outbox translation to include workspace events.
  • Added filter-based bulk deletion of authorization relationships to streamline cleanup (e.g., tenant root pointers).

• Tests

  • Expanded unit tests for workspace behavior, event emissions, translation ordering, and bulk-deletion handling.

[coderabbitai]

Walkthrough

This PR adds a Workspace aggregate (factory methods, validation, deletion signaling, event collection) and exports it from iam.domain.aggregates. It restructures IAM domain events into a new events package with per-entity modules (tenant, group, workspace, api_key) and a central events.init providing a DomainEvent union. The outbox translator and worker are extended to translate and apply WorkspaceCreated/WorkspaceDeleted and a new DeleteRelationshipsByFilter operation. The SpiceDB client, authorization protocols, and observability probes gained filter-based deletion support. Unit tests for the workspace aggregate, translator, worker, and SpiceDB client validations were added/updated.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant WorkspaceAggregate as "Workspace Aggregate"
    participant DomainEvents as "Domain Events"
    participant Translator as "IAMEventTranslator"
    participant OutboxWorker as "Outbox Worker"
    participant SpiceDB as "SpiceDB / AuthZ"

    Client->>WorkspaceAggregate: create(name, tenant_id[, parent_id])
    activate WorkspaceAggregate
    WorkspaceAggregate->>WorkspaceAggregate: validate, gen id, timestamps
    WorkspaceAggregate->>DomainEvents: append WorkspaceCreated
    WorkspaceAggregate-->>Client: return workspace
    deactivate WorkspaceAggregate

    Client->>WorkspaceAggregate: mark_for_deletion()
    WorkspaceAggregate->>DomainEvents: append WorkspaceDeleted

    Note over DomainEvents,Translator: outbox translation pipeline
    DomainEvents->>Translator: translate(event)
    Translator->>OutboxWorker: emit SpiceDB operations (WriteRelationship / DeleteRelationshipsByFilter / DeleteRelationship)
    OutboxWorker->>SpiceDB: apply operations (write/delete or delete_by_filter)
    SpiceDB-->>OutboxWorker: ack / error
    OutboxWorker-->>Translator: observability callbacks (success/failure)

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• feat(api): authorization abstractions and SpiceDB client #85: Adds and extends the SpiceDB/authorization surface (delete_relationships_by_filter, client/protocol/probe changes) referenced by this PR.
• feat(api.iam): persist tenant membership #178: Modifies IAM domain event modeling and outbox translation/aggregate handling; overlaps with event reorganization and translator updates in this PR.

🚥 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 accurately describes the main change: introducing Workspace domain objects (aggregate, events, and supporting infrastructure) in the IAM module.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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/workspace-aggregate

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 Fix all issues with AI agents

In `@src/api/iam/domain/aggregates/workspace.py`:
- Around line 91-112: The WorkspaceCreated event uses a new datetime instead of
the captured now, causing timestamp drift; update the aggregate factory in
Workspace.create (or the classmethod constructing workspace) to pass the
previously captured now variable as occurred_at when appending WorkspaceCreated
(use occurred_at=now) and remove the unnecessary conditional that checks
parent_workspace_id.value since parent_workspace_id is required—directly use
parent_workspace_id.value for the event payload.
- Around line 136-155: The Workspace.create_root flow creates a now timestamp
but then uses datetime.now(UTC) again for the WorkspaceCreated event; change the
event to reuse the previously computed now (the local variable now) so the
aggregate's created_at/updated_at and the WorkspaceCreated.occurred_at are
identical — update the call that appends WorkspaceCreated (referencing
WorkspaceCreated and workspace._pending_events.append in the create_root/cls
constructor flow) to pass occurred_at=now instead of datetime.now(UTC).

In `@src/api/iam/domain/events/tenant.py`:
- Around line 72-86: Fix the small typo in the TenantMemberRemoved docstring:
update the occurred_at attribute description in the class TenantMemberRemoved
(docstring text "When this even occurred (UTC)") to read "When this event
occurred (UTC)". Ensure the rest of the docstring formatting and attribute order
(tenant_id, user_id, removed_by, occurred_at) remains unchanged.
- Around line 53-70: Fix the typo in the docstring of the TenantMemberAdded
dataclass: update the "occurred_at" description from "When this even occurred
(UTC)" to "When this event occurred (UTC)" within the TenantMemberAdded class
documentation so the docstring correctly describes the occurred_at field.

In `@src/api/iam/infrastructure/outbox/translator.py`:
- Around line 326-362: Update the workspace translators to use
RelationType.PARENT (not RelationType.TENANT) and emit/delete the correct
relationships in _translate_workspace_created and _translate_workspace_deleted:
when creating, add a parent relation from workspace to tenant
(workspace:<id>#parent@tenant:<tenant_id>) if no parent_workspace_id, or to a
parent workspace (workspace:<id>#parent@workspace:<parent_id>) when
payload["parent_workspace_id"] is present; additionally, if payload["is_root"]
is True add a WriteRelationship for tenant root_workspace
(tenant:<tenant_id>#root_workspace@workspace:<id>); mirror these three deletes
in _translate_workspace_deleted. Locate and update the methods
_translate_workspace_created and _translate_workspace_deleted and replace
RelationType.TENANT with RelationType.PARENT where appropriate and add the extra
WriteRelationship/DeleteRelationship entries for parent_workspace_id and is_root
handling.

🧹 Nitpick comments (1)

src/api/iam/domain/aggregates/workspace.py (1)

52-55: Minor redundancy in name validation.

not name already catches empty strings (and None if somehow passed), making len(name) < 1 redundant.

♻️ Suggested simplification

     def _validate_name(self, name: str) -> None:
         """Validate workspace name length."""
-        if not name or len(name) < 1 or len(name) > 512:
+        if not name or len(name) > 512:
             raise ValueError("Workspace name must be between 1 and 512 characters")

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/api/shared_kernel/authorization/spicedb/client.py`:
- Around line 15-25: Add an explicit input validation before constructing a
SubjectFilter: if subject_id (optional_subject_id) is provided but subject_type
is missing, raise a clear error (e.g., a SpiceDBPermissionError or ValueError)
rather than attempting to build SubjectFilter and letting the authzed client
throw; update the logic around SubjectFilter creation in client.py (where
SubjectFilter is instantiated) to check "if subject_id and not subject_type" and
raise the validation error with a descriptive message so invalid inputs are
caught early.

🧹 Nitpick comments (2)

src/api/iam/domain/aggregates/workspace.py (2)

52-55: Minor: Redundant validation condition.

The check not name or len(name) < 1 is redundant—not name is true when name is empty (""), and an empty string has len(name) == 0, which is already < 1. Simplify to len(name) < 1 or len(name) > 512.

♻️ Proposed simplification

     def _validate_name(self, name: str) -> None:
         """Validate workspace name length."""
-        if not name or len(name) < 1 or len(name) > 512:
+        if len(name) < 1 or len(name) > 512:
             raise ValueError("Workspace name must be between 1 and 512 characters")

---

156-175: Consider capturing timestamp for consistency with factory methods.

Unlike create() and create_root(), mark_for_deletion() calls datetime.now(UTC) directly in the event construction. While this doesn't cause functional issues (no entity timestamp updates here), capturing now first would maintain a consistent pattern across all methods and simplify future changes if updated_at tracking is added for deletions.

♻️ Optional consistency improvement

     def mark_for_deletion(self) -> None:
         """Mark the workspace for deletion and record the WorkspaceDeleted event.
         ...
         """
+        now = datetime.now(UTC)
         self._pending_events.append(
             WorkspaceDeleted(
                 workspace_id=self.id.value,
                 tenant_id=self.tenant_id.value,
                 parent_workspace_id=self.parent_workspace_id.value
                 if self.parent_workspace_id
                 else None,
                 is_root=self.is_root,
-                occurred_at=datetime.now(UTC),
+                occurred_at=now,
             )
         )