ubiquitous-invention/plans/Plan-multitenant-saas-hardening/Epic-tenant-lifecycle/Task-audit-instrument-objects-mutations.md

---
kind: task
slug: audit-instrument-objects-mutations
title: Audit-instrument every mutation in the objects router
plan_slug: multitenant-saas-hardening
epic_slug: tenant-lifecycle
status: draft
priority: P2
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-06-02"
---

# Task summary

`Task-workspace-soft-delete-and-audit` shipped `recordAudit()` and instrumented every mutation in `workspaces` and `invites`. The objects router has ~10 mutation procedures (`create`, `update`, `move`, `archive`, `restore`, `setProperties`, `bulkUpdate`, `addAssignee`, `removeAssignee`, etc. — verify against the current router before scoping).

Deferred from the parent task because:

1. Auditing ALL of them risks producing low-signal-high-noise rows. We want a thoughtful cut (e.g. skip property edits, keep status changes).
2. Some procedures fan out to multiple rows (`bulkUpdate`) — one audit row per batch with a `count` field is probably right, not one per affected object.

## Subtasks

- [ ] Enumerate every mutation in `apps/web/server/routers/objects.ts` with a one-line "should we audit this?" verdict.
- [ ] Pick the audit-worthy cut and add `recordAudit` calls to each, with `metadata` that's actually useful (title for create, before/after status for status change, count for bulk).
- [ ] Decide on a fan-out policy for bulk procedures — one row per batch (recommended) vs. one row per affected object (noisy).
- [ ] Update the audit view to render object-action labels.

## Acceptance criteria

- [ ] Every audit-worthy `objects` mutation writes one or more audit rows.
- [ ] No-audit procedures are documented inline ("audit-skip: …").

## Links

- Parent: `./Task-workspace-soft-delete-and-audit.md`
- Epic: `./Epic-tenant-lifecycle.md`
feat(audit): append-only audit_log, workspace archive cascade + restore, audit view Soft-delete cascade was the missing half of archive: stamping workspaces.archived_at alone left objects visible to anyone with a direct id. The cascade runs in one transaction so the partial state isn't reachable, and restore inverts it for any archived row in the workspace — provenance-blind on purpose until we have a use case that needs to distinguish per-workspace from per-object archives. audit_log keeps the keyset index on (workspace_id, created_at) and the actor_user_id FK with onDelete set null. recordAudit() refuses to write a null actor without a metadata.system_actor label so the audit view always has something to render. workspaces and invites mutations call recordAudit on success; objects-router instrumentation and the markdown importer's system-actor flow are filed as P2 follow-ups because each needs a thoughtful "what's audit-worthy?" pass, not mechanical wiring. Settings → Audit log lives at /<slug>/settings/audit, owner-gated, keyset-paginated. ACTION_LABELS is small on purpose; new actions fall back to their raw key so missing a label degrades gracefully. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-06-02 16:35:16 -04:00			`---`
			`kind: task`
			`slug: audit-instrument-objects-mutations`
			`title: Audit-instrument every mutation in the objects router`
			`plan_slug: multitenant-saas-hardening`
			`epic_slug: tenant-lifecycle`
			`status: draft`
			`priority: P2`
			`tenant_id: global`
			`owner: unassigned`
			`cursor_todo_id: null`
			`updated_at: "2026-06-02"`
			`---`

			`# Task summary`

			`Task-workspace-soft-delete-and-audit` shipped `recordAudit()` and instrumented every mutation in `workspaces` and `invites`. The objects router has ~10 mutation procedures (`create`, `update`, `move`, `archive`, `restore`, `setProperties`, `bulkUpdate`, `addAssignee`, `removeAssignee`, etc. — verify against the current router before scoping).

			`Deferred from the parent task because:`

			`1. Auditing ALL of them risks producing low-signal-high-noise rows. We want a thoughtful cut (e.g. skip property edits, keep status changes).`
			2. Some procedures fan out to multiple rows (`bulkUpdate`) — one audit row per batch with a `count` field is probably right, not one per affected object.

			`## Subtasks`

			- [ ] Enumerate every mutation in `apps/web/server/routers/objects.ts` with a one-line "should we audit this?" verdict.
			- [ ] Pick the audit-worthy cut and add `recordAudit` calls to each, with `metadata` that's actually useful (title for create, before/after status for status change, count for bulk).
			`- [ ] Decide on a fan-out policy for bulk procedures — one row per batch (recommended) vs. one row per affected object (noisy).`
			`- [ ] Update the audit view to render object-action labels.`

			`## Acceptance criteria`

			- [ ] Every audit-worthy `objects` mutation writes one or more audit rows.
			`- [ ] No-audit procedures are documented inline ("audit-skip: …").`

			`## Links`

			- Parent: `./Task-workspace-soft-delete-and-audit.md`
			- Epic: `./Epic-tenant-lifecycle.md`