@orthacms/activity-server 0.4.2 → 0.5.0

package/dist/lib/activity/services/activity.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/services/activity.service.ts"],"names":[],"mappings":"AAYA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EACR,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACtB,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,KAAK,EAER,gBAAgB,EACnB,MAAM,wBAAwB,CAAC;AAQhC;;;;;;GAMG;AACH,qBACa,eAAgB,YAAW,gBAAgB;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ;IAE3D;;;;;;;;;;OAUG;IACG,MAAM,CACR,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,GAAE,gBAA0B,GACrC,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8ClE;;;;;;OAMG;YACW,SAAS;IAWvB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAQ9B"}
+{"version":3,"file":"activity.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/services/activity.service.ts"],"names":[],"mappings":"AAYA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EACR,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACtB,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,KAAK,EAER,gBAAgB,EACnB,MAAM,wBAAwB,CAAC;AAQhC;;;;;;GAMG;AACH,qBACa,eAAgB,YAAW,gBAAgB;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ;IAE3D;;;;;;;;;;OAUG;IACG,MAAM,CACR,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,GAAE,gBAA0B,GACrC,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgDlE;;;;;;OAMG;YACW,SAAS;IAWvB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IA4BrB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAQ9B"}

package/dist/lib/activity/services/activity.service.js

@@ -75,7 +75,9 @@ let ActivityService = class ActivityService {
                 subjectType: schema_1.activityEvents.subjectType,
                 subjectId: schema_1.activityEvents.subjectId,
                 actorId: schema_1.activityEvents.actorId,
+                actorType: schema_1.activityEvents.actorType,
                 actorEmail: schema_1.activityEvents.actorEmail,
+                workspaceId: schema_1.activityEvents.workspaceId,
                 meta: schema_1.activityEvents.meta,
                 at: schema_1.activityEvents.at
             })
@@ -119,6 +121,10 @@ let ActivityService = class ActivityService {
             ? (0, drizzle_orm_1.eq)(schema_1.activityEvents.subjectId, query.subjectId)
             : undefined, query.actorId
             ? (0, drizzle_orm_1.eq)(schema_1.activityEvents.actorId, query.actorId)
+            : undefined, query.actorType
+            ? (0, drizzle_orm_1.eq)(schema_1.activityEvents.actorType, query.actorType)
+            : undefined, query.workspaceId
+            ? (0, drizzle_orm_1.eq)(schema_1.activityEvents.workspaceId, query.workspaceId)
             : undefined, query.kind && query.kind.length > 0
             ? (0, drizzle_orm_1.inArray)(schema_1.activityEvents.kind, query.kind)
             : undefined, this.actorEmailPredicate(query.actorEmail), query.from

package/dist/lib/activity/types/activity-view.d.ts

@@ -16,8 +16,25 @@ export interface ActivityEventView {
     subjectId: string;
     /** Who performed it, or `null` for a system-initiated event. */
     actorId: string | null;
-    /** Frozen email snapshot of the actor, or `null`. */
+    /**
+     * What {@link actorId} names — `'user'` for a person, `'api_token'` for an
+     * external credential, `null` when there is no actor. A client rendering
+     * the actor needs this: the two ids come from different tables and lead to
+     * different pages, and an `actorEmail` that is really a token label would
+     * otherwise be indistinguishable from a person's address.
+     */
+    actorType: string | null;
+    /**
+     * Frozen email snapshot of the actor, or `null`. For an `api_token` actor
+     * this carries the token's **label** instead — a token has no email, and a
+     * row showing a bare uuid names nothing a reader recognises.
+     */
     actorEmail: string | null;
+    /**
+     * The workspace the action happened in, or `null` when it belongs to none
+     * (an invite, a role change, the creation of a workspace itself).
+     */
+    workspaceId: string | null;
     /** Open per-kind payload, or `null`. */
     meta: Record<string, unknown> | null;
     /** Logical event time. */

package/dist/lib/activity/types/activity-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-view.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/types/activity-view.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrC,0BAA0B;IAC1B,EAAE,EAAE,IAAI,CAAC;CACZ;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC7B,+BAA+B;IAC/B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"activity-view.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/types/activity-view.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrC,0BAA0B;IAC1B,EAAE,EAAE,IAAI,CAAC;CACZ;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC7B,+BAA+B;IAC/B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;CACpB"}

package/dist/lib/activity.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.module.d.ts","sourceRoot":"","sources":["../../src/lib/activity.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAOvD;;;;;;;;;;;;;GAaG;AACH,qBACa,cAAc;IACvB,qFAAqF;IACrF,MAAM,CAAC,OAAO,IAAI,aAAa;CAiBlC"}
+{"version":3,"file":"activity.module.d.ts","sourceRoot":"","sources":["../../src/lib/activity.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,MAAM,gBAAgB,CAAC;AASvD;;;;;;;;;;;;;GAaG;AACH,qBACa,cAAc;IACvB,qFAAqF;IACrF,MAAM,CAAC,OAAO,IAAI,aAAa;CA0BlC"}

package/dist/lib/activity.module.js

@@ -6,6 +6,8 @@ const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
 const identity_server_1 = require("@orthacms/identity-server");
 const list_activity_controller_1 = require("./activity/controllers/list-activity.controller");
+const dead_letters_controller_1 = require("./activity/controllers/dead-letters.controller");
+const entry_activity_controller_1 = require("./activity/controllers/entry-activity.controller");
 const activity_service_1 = require("./activity/services/activity.service");
 const audit_event_subscriber_1 = require("./activity/infrastructure/audit-event.subscriber");
 const activity_tool_provider_1 = require("./copilot/activity-tool.provider");
@@ -29,7 +31,16 @@ let ActivityModule = ActivityModule_1 = class ActivityModule {
         return {
             module: ActivityModule_1,
             global: true,
-            controllers: [list_activity_controller_1.ListActivityController],
+            controllers: [
+                // The scoped route is declared **before** the global one:
+                // `activity/entries/:id` and `activity` are different paths, but
+                // keeping the literal-prefixed controller first is the same
+                // ordering habit the content routes follow, and it stays true
+                // as the pattern set grows.
+                entry_activity_controller_1.EntryActivityController,
+                list_activity_controller_1.ListActivityController,
+                dead_letters_controller_1.DeadLettersController
+            ],
             providers: [
                 activity_service_1.ActivityService,
                 audit_event_subscriber_1.AuditEventSubscriber,

package/dist/lib/docs/activity-schemas.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The response schemas of the activity plugin's three read routes, as plain
+ * OpenAPI objects.
+ *
+ * `ActivityEventView`, `ActivityListView` and `DeadLetterListView` are
+ * TypeScript `interface`s, so the OpenAPI scanner emits a bare
+ * `{ '200': { description: '' } }` for all three — see
+ * `packages/bootstrap/server/AGENTS.md` → "The response-schema gap". These are
+ * what the `decorate` pass writes in their place.
+ *
+ * Pure: no document, no Nest, no database.
+ */
+/** A JSON Schema fragment, as it appears in the OpenAPI document. */
+export type OpenApiSchema = Record<string, unknown>;
+/** A `$ref` to one of {@link ACTIVITY_SCHEMAS}. */
+export declare function ref(name: string): OpenApiSchema;
+/** The activity plugin's response schemas, keyed by component name. */
+export declare const ACTIVITY_SCHEMAS: Record<string, OpenApiSchema>;
+//# sourceMappingURL=activity-schemas.d.ts.map

package/dist/lib/docs/activity-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/activity-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,mDAAmD;AACnD,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE/C;AAiBD,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAmJ1D,CAAC"}

package/dist/lib/docs/activity-schemas.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * The response schemas of the activity plugin's three read routes, as plain
+ * OpenAPI objects.
+ *
+ * `ActivityEventView`, `ActivityListView` and `DeadLetterListView` are
+ * TypeScript `interface`s, so the OpenAPI scanner emits a bare
+ * `{ '200': { description: '' } }` for all three — see
+ * `packages/bootstrap/server/AGENTS.md` → "The response-schema gap". These are
+ * what the `decorate` pass writes in their place.
+ *
+ * Pure: no document, no Nest, no database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVITY_SCHEMAS = void 0;
+exports.ref = ref;
+/** A `$ref` to one of {@link ACTIVITY_SCHEMAS}. */
+function ref(name) {
+    return { $ref: `#/components/schemas/${name}` };
+}
+/**
+ * The paging envelope both log routes answer in. Written twice rather than
+ * `$ref`-ed into one, because the two routes are two different questions and
+ * the envelope is the only thing they share.
+ */
+const PAGE_PROPERTIES = {
+    total: {
+        type: 'integer',
+        description: 'Events matching the filters across every page, not just this one.'
+    },
+    page: { type: 'integer', description: 'The 1-based page number, echoed.' },
+    pageSize: { type: 'integer', description: 'The page size, echoed.' }
+};
+/** The activity plugin's response schemas, keyed by component name. */
+exports.ACTIVITY_SCHEMAS = {
+    ActivityEvent: {
+        type: 'object',
+        description: 'One recorded action. Mirrors the `activity_events` row minus `createdAt` — the immutable write time is an internal detail and never reaches the wire.',
+        properties: {
+            id: { type: 'string', format: 'uuid' },
+            kind: {
+                type: 'string',
+                description: 'The `domain.action` kind, e.g. `user.signed_in` or `content.published`. Deliberately an open string: each emitting plugin owns its own kinds, so this is not an enum the document can close.'
+            },
+            subjectType: {
+                type: 'string',
+                description: 'What kind of thing was acted upon, e.g. `user`, `workspace`, `content_entry`.'
+            },
+            subjectId: {
+                type: 'string',
+                description: 'The acted-upon entity’s id. **Text, not a uuid** — subjects are not always uuid-keyed.'
+            },
+            actorId: {
+                type: 'string',
+                format: 'uuid',
+                nullable: true,
+                description: 'Who performed it, or `null` for a system-initiated event. Carries no foreign key: the actor may be deleted, and the audit row must outlive them.'
+            },
+            actorType: {
+                type: 'string',
+                nullable: true,
+                description: 'What `actorId` names — `user` for a person, `api_token` for an external credential, `null` when there is no actor. Not constrained to those two: the column is open text, and a row written before it existed carries `null`.'
+            },
+            actorEmail: {
+                type: 'string',
+                nullable: true,
+                description: 'Frozen email snapshot of the actor at record time, so the trail stays readable after the user row is gone. For an `api_token` actor this carries the token’s **label** instead — a token has no email.'
+            },
+            workspaceId: {
+                type: 'string',
+                format: 'uuid',
+                nullable: true,
+                description: 'The workspace the action happened in, or `null` when it belongs to none — an invite, a role change, the creation of a workspace itself.'
+            },
+            meta: {
+                type: 'object',
+                additionalProperties: true,
+                nullable: true,
+                description: 'Open per-kind payload, owned by the emitting plugin. No shape is promised here; a consumer branches on `kind` first.'
+            },
+            at: {
+                type: 'string',
+                format: 'date-time',
+                description: 'Logical event time — what the list sorts on.'
+            }
+        },
+        required: [
+            'id',
+            'kind',
+            'subjectType',
+            'subjectId',
+            'actorId',
+            'actorType',
+            'actorEmail',
+            'workspaceId',
+            'meta',
+            'at'
+        ]
+    },
+    ActivityListView: {
+        type: 'object',
+        description: 'One page of audit events, newest first by default.',
+        properties: {
+            items: { type: 'array', items: ref('ActivityEvent') },
+            ...PAGE_PROPERTIES
+        },
+        required: ['items', 'total', 'page', 'pageSize']
+    },
+    ActivityDeadLetter: {
+        type: 'object',
+        description: 'One outbox event that exhausted its delivery attempts and is no longer retried. **The payload is deliberately absent** — it is arbitrary domain data, some of it user-authored, and this route answers "what is stuck", not "replay it".',
+        properties: {
+            id: {
+                type: 'string',
+                format: 'uuid',
+                description: 'The event id — the handle for a manual replay (clearing `attempts`).'
+            },
+            kind: {
+                type: 'string',
+                description: 'The event kind that could not be delivered.'
+            },
+            aggregateType: {
+                type: 'string',
+                description: 'The aggregate root’s type.'
+            },
+            aggregateId: {
+                type: 'string',
+                description: 'The aggregate root’s id.'
+            },
+            occurredAt: {
+                type: 'string',
+                format: 'date-time',
+                description: 'When the fact occurred. The list orders on it.'
+            },
+            attempts: {
+                type: 'integer',
+                description: 'Delivery attempts spent before it parked — at or above the dispatcher’s ceiling, which is what makes it a dead letter.'
+            },
+            lastError: {
+                type: 'string',
+                nullable: true,
+                description: 'Why the last attempt failed, truncated to roughly a line. Stack traces stay in the logs.'
+            }
+        },
+        required: [
+            'id',
+            'kind',
+            'aggregateType',
+            'aggregateId',
+            'occurredAt',
+            'attempts',
+            'lastError'
+        ]
+    },
+    ActivityDeadLetterListView: {
+        type: 'object',
+        description: 'The parked events. A non-zero `total` means the audit trail is incomplete.',
+        properties: {
+            total: {
+                type: 'integer',
+                description: 'How many events have given up in total, ignoring `limit`.'
+            },
+            items: { type: 'array', items: ref('ActivityDeadLetter') }
+        },
+        required: ['total', 'items']
+    }
+};

package/dist/lib/docs/describe-activity-api.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The activity plugin's pass over the host's OpenAPI document.
+ *
+ * Three read routes, three hand-written `interface`s, and therefore three
+ * operations the scanner leaves as `{ '200': { description: '' } }` — see
+ * `packages/bootstrap/server/AGENTS.md` → "The response-schema gap". This
+ * writes the schemas on the way past, the way `content-server`'s pass does.
+ *
+ * Pure: it takes the document and mutates only the paths this plugin owns.
+ */
+import type { OpenApiDocument } from '@orthacms/bootstrap-server';
+/**
+ * Adds this plugin's schemas to `document` and attaches them to its own three
+ * operations.
+ */
+export declare function describeActivityApi(document: OpenApiDocument): void;
+//# sourceMappingURL=describe-activity-api.d.ts.map

package/dist/lib/docs/describe-activity-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-activity-api.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/describe-activity-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAuElE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CA0BnE"}

package/dist/lib/docs/describe-activity-api.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * The activity plugin's pass over the host's OpenAPI document.
+ *
+ * Three read routes, three hand-written `interface`s, and therefore three
+ * operations the scanner leaves as `{ '200': { description: '' } }` — see
+ * `packages/bootstrap/server/AGENTS.md` → "The response-schema gap". This
+ * writes the schemas on the way past, the way `content-server`'s pass does.
+ *
+ * Pure: it takes the document and mutates only the paths this plugin owns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeActivityApi = describeActivityApi;
+const activity_schemas_1 = require("./activity-schemas");
+/**
+ * Matches `<prefix>/activity<rest>`, capturing what follows.
+ *
+ * The empty capture is the log itself, so the group has to be optional rather
+ * than `(.*)`-greedy off a trailing slash the document does not write:
+ * `/api/activity` has no trailing slash, and the two sub-routes do.
+ */
+const ACTIVITY_ROUTE_RE = /\/activity(\/.*)?$/;
+/** The plugin's routes, keyed by what follows `/activity`. */
+const ROUTES = {
+    '': {
+        get: {
+            schema: 'ActivityListView',
+            description: 'One page of the deployment-wide audit log, matching the filters.'
+        }
+    },
+    '/entries/{entryId}': {
+        get: {
+            schema: 'ActivityListView',
+            description: 'One page of this entry’s own history, scoped to the open workspace. An entry id from another workspace reads as an empty page rather than as somebody else’s history.'
+        }
+    },
+    '/dead-letters': {
+        get: {
+            schema: 'ActivityDeadLetterListView',
+            description: 'The parked events, newest first. `total` ignores `limit`, so a caller can tell "nothing is stuck" from "the first page is full".'
+        }
+    }
+};
+/**
+ * Writes a success schema onto whichever 2xx key the scanner already emitted,
+ * so this never invents a status code the API does not return.
+ */
+function setSuccessResponse(operation, schema, description) {
+    const responses = operation.responses ?? {};
+    const key = Object.keys(responses).find((code) => /^2\d\d$/.test(code));
+    if (!key || key === '204') {
+        return;
+    }
+    responses[key] = {
+        description,
+        content: { 'application/json': { schema } }
+    };
+    operation.responses = responses;
+}
+/**
+ * Adds this plugin's schemas to `document` and attaches them to its own three
+ * operations.
+ */
+function describeActivityApi(document) {
+    document.components ??= {};
+    document.components.schemas ??= {};
+    Object.assign(document.components.schemas, activity_schemas_1.ACTIVITY_SCHEMAS);
+    for (const [route, item] of Object.entries(document.paths)) {
+        const match = ACTIVITY_ROUTE_RE.exec(route);
+        if (!match) {
+            continue;
+        }
+        const byMethod = ROUTES[match[1] ?? ''];
+        if (!byMethod) {
+            continue;
+        }
+        for (const [method, operation] of Object.entries(item)) {
+            const spec = byMethod[method];
+            if (!spec || !operation || typeof operation !== 'object') {
+                continue;
+            }
+            setSuccessResponse(operation, (0, activity_schemas_1.ref)(spec.schema), spec.description);
+        }
+    }
+}

package/dist/lib/schema/activity-events.d.ts

@@ -4,16 +4,36 @@
  * Deliberate isolation choices (the audit log must outlive what it records):
  * - `actorId` is a uuid with **no FK** — the actor may later be deleted, but
  *   the audit row must remain.
+ * - `actorType` says what `actorId` names — a person (`user`) or an API
+ *   credential (`api_token`). Without it `actor_id` meant "a users row" and
+ *   nothing else, so a write made with a bearer token had to pass **no** actor
+ *   rather than name a person who did not do it: every write over the public
+ *   REST API, GraphQL and MCP was recorded as "System", and which of a
+ *   workspace's tokens did it was not recoverable from anywhere. It is nullable
+ *   because a system-initiated event still has no actor at all, and because
+ *   every row written before this column existed names a user.
  * - `actorEmail` is a frozen snapshot of the actor's email at record time, so
  *   the trail stays readable even after the user row is gone or renamed.
  * - `subjectId` is **text**, not uuid — subjects are not always users and not
  *   always uuid-keyed.
+ * - `workspaceId` is the workspace the action happened in, or `null` when it
+ *   happened in none. The trail records invites, role changes and workspace
+ *   lifecycle alongside content edits and **several of those belong to no
+ *   workspace at all**, which is why this is nullable and why it is not a
+ *   scoping boundary: the log stays deployment-wide and `activity:read`
+ *   remains what bounds it. What the column buys is the ability to *ask* a
+ *   workspace-shaped question — "what happened in this workspace" — which
+ *   previously had no answer at any price, and which is why the content
+ *   insights punchcard reads the revision table instead of this one. Populated
+ *   from the emitting event's own `payload.workspaceId`; a producer that has a
+ *   workspace puts it there.
  * - `meta` is an open jsonb payload; each emitting plugin owns its shape.
  * - `at` is the logical event time (defaults to now); `createdAt` is the
  *   immutable write time, dropped from the read API.
  *
- * Indexed for the three query shapes the read API serves: a subject's history,
- * an actor's history, and a kind's history — each time-ordered.
+ * Indexed for the four query shapes the read API serves: a subject's history,
+ * an actor's history, a kind's history, and a workspace's history — each
+ * time-ordered.
  */
 export declare const activityEvents: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "activity_events";
@@ -104,6 +124,23 @@ export declare const activityEvents: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        actorType: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_type";
+            tableName: "activity_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         actorEmail: import("drizzle-orm/pg-core").PgColumn<{
             name: "actor_email";
             tableName: "activity_events";
@@ -121,6 +158,23 @@ export declare const activityEvents: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        workspaceId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workspace_id";
+            tableName: "activity_events";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         meta: import("drizzle-orm/pg-core").PgColumn<{
             name: "meta";
             tableName: "activity_events";

package/dist/lib/schema/activity-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-events.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/activity-events.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwB1B,CAAC"}
+{"version":3,"file":"activity-events.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/activity-events.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2B1B,CAAC"}

package/dist/lib/schema/activity-events.js

@@ -8,16 +8,36 @@ const pg_core_1 = require("drizzle-orm/pg-core");
  * Deliberate isolation choices (the audit log must outlive what it records):
  * - `actorId` is a uuid with **no FK** — the actor may later be deleted, but
  *   the audit row must remain.
+ * - `actorType` says what `actorId` names — a person (`user`) or an API
+ *   credential (`api_token`). Without it `actor_id` meant "a users row" and
+ *   nothing else, so a write made with a bearer token had to pass **no** actor
+ *   rather than name a person who did not do it: every write over the public
+ *   REST API, GraphQL and MCP was recorded as "System", and which of a
+ *   workspace's tokens did it was not recoverable from anywhere. It is nullable
+ *   because a system-initiated event still has no actor at all, and because
+ *   every row written before this column existed names a user.
  * - `actorEmail` is a frozen snapshot of the actor's email at record time, so
  *   the trail stays readable even after the user row is gone or renamed.
  * - `subjectId` is **text**, not uuid — subjects are not always users and not
  *   always uuid-keyed.
+ * - `workspaceId` is the workspace the action happened in, or `null` when it
+ *   happened in none. The trail records invites, role changes and workspace
+ *   lifecycle alongside content edits and **several of those belong to no
+ *   workspace at all**, which is why this is nullable and why it is not a
+ *   scoping boundary: the log stays deployment-wide and `activity:read`
+ *   remains what bounds it. What the column buys is the ability to *ask* a
+ *   workspace-shaped question — "what happened in this workspace" — which
+ *   previously had no answer at any price, and which is why the content
+ *   insights punchcard reads the revision table instead of this one. Populated
+ *   from the emitting event's own `payload.workspaceId`; a producer that has a
+ *   workspace puts it there.
  * - `meta` is an open jsonb payload; each emitting plugin owns its shape.
  * - `at` is the logical event time (defaults to now); `createdAt` is the
  *   immutable write time, dropped from the read API.
  *
- * Indexed for the three query shapes the read API serves: a subject's history,
- * an actor's history, and a kind's history — each time-ordered.
+ * Indexed for the four query shapes the read API serves: a subject's history,
+ * an actor's history, a kind's history, and a workspace's history — each
+ * time-ordered.
  */
 exports.activityEvents = (0, pg_core_1.pgTable)('activity_events', {
     id: (0, pg_core_1.uuid)('id').primaryKey().defaultRandom(),
@@ -25,7 +45,9 @@ exports.activityEvents = (0, pg_core_1.pgTable)('activity_events', {
     subjectType: (0, pg_core_1.text)('subject_type').notNull(),
     subjectId: (0, pg_core_1.text)('subject_id').notNull(),
     actorId: (0, pg_core_1.uuid)('actor_id'),
+    actorType: (0, pg_core_1.text)('actor_type'),
     actorEmail: (0, pg_core_1.text)('actor_email'),
+    workspaceId: (0, pg_core_1.uuid)('workspace_id'),
     meta: (0, pg_core_1.jsonb)('meta'),
     at: (0, pg_core_1.timestamp)('at', { withTimezone: true }).notNull().defaultNow(),
     createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true })
@@ -34,5 +56,6 @@ exports.activityEvents = (0, pg_core_1.pgTable)('activity_events', {
 }, (table) => [
     (0, pg_core_1.index)('activity_events_subject_idx').on(table.subjectType, table.subjectId, table.at),
     (0, pg_core_1.index)('activity_events_actor_idx').on(table.actorId, table.at),
-    (0, pg_core_1.index)('activity_events_kind_idx').on(table.kind, table.at)
+    (0, pg_core_1.index)('activity_events_kind_idx').on(table.kind, table.at),
+    (0, pg_core_1.index)('activity_events_workspace_idx').on(table.workspaceId, table.at)
 ]);

package/dist/lib/utils/activity-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-plugin.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/activity-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAS7C"}
+{"version":3,"file":"activity-plugin.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/activity-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAY7C"}

package/dist/lib/utils/activity-plugin.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ActivityPlugin = ActivityPlugin;
 const node_path_1 = require("node:path");
 const activity_module_1 = require("../activity.module");
+const describe_activity_api_1 = require("../docs/describe-activity-api");
 /**
  * Server plugin for the audit log. A plain {@link ServerPlugin} — the feature
  * carries no host config.
@@ -33,6 +34,9 @@ function ActivityPlugin() {
         migrations: {
             dir: () => (0, node_path_1.join)(__dirname, '../../../migrations'),
             table: '__drizzle_migrations_activity'
-        }
+        },
+        // The three read routes answer plain `interface`s, which the OpenAPI
+        // scanner cannot see and no configuration switch can infer.
+        docs: { decorate: describe_activity_api_1.describeActivityApi }
     };
 }

package/migrations/0001_actor_type_and_workspace.sql

@@ -0,0 +1,8 @@
+ALTER TABLE "activity_events" ADD COLUMN "actor_type" text;--> statement-breakpoint
+ALTER TABLE "activity_events" ADD COLUMN "workspace_id" uuid;--> statement-breakpoint
+CREATE INDEX "activity_events_workspace_idx" ON "activity_events" USING btree ("workspace_id","at");--> statement-breakpoint
+-- Backfill: every actor recorded before this column existed is a person. Nothing
+-- else could be one — a token-authenticated write passed no actor at all — so
+-- this is a statement of fact rather than a guess, and it keeps a reader from
+-- having to treat a null `actor_type` on an actored row as "unknown kind".
+UPDATE "activity_events" SET "actor_type" = 'user' WHERE "actor_id" IS NOT NULL AND "actor_type" IS NULL;