# Epic 1 Addendum: actorId in Canonical Envelope — Jira Ticket

## Business Justification

We realized that our `event_store` database naturally forms a perfect, read-only **Audit Log / System Information timeline** for our users. However, our current Canonical JSON Envelope tracks *what* changed and *when*, but not *who* made the change. We need to amend the schema contract to include the user's identity before the downstream event emitters are fully built.

## Proposed Solution

Update the base JSON envelope definition to include an **actorId** property. This will store the unique identifier (`users.id` value from the tenant's `users` table) of the human user or automated system that triggered the data mutation.

## Technical Requirements

- **Schema Definition Update:** Add `"actorId"` as a top-level string property to the V10 Canonical Event Envelope schema.
- **Validation Rules:** The field must be **required**. If the change was triggered by a human via the SuiteX UI, it should be their SuiteX User ID. If the change was triggered by an automated background script or NetSuite system process, it should be hardcoded to `"system"`.
- **Documentation Update:** Update the central API contract documentation (Swagger/Postman/Wiki) to reflect this new required field so the Epic 4 (SuiteX Emitter) and Epic 6 (NetSuite Emitter) developers can implement it immediately.

## Acceptance Criteria (Definition of Done)

### Scenario 1 (Schema Validation)

- **Given** the updated schema.
- **When** a payload is validated without an `actorId`.
- **Then** the Stage 1 Structural Validator correctly rejects it.

### Scenario 2 (System Actor)

- **Given** an automated background job updates a record.
- **When** the event is formatted.
- **Then** the `actorId` strictly reads `"system"`.

### Scenario 3 (Team Communication)

- **Given** the schema is merged.
- **When** the documentation is published.
- **Then** the developers working on the mock server and the SuiteX observers are notified of the required contract change.

## Deliverables

- Updated Canonical JSON Schema file (v1.1).
- Updated dummy JSON payload examples showing the new `"actorId": "8832"` field.
- A Slack/Teams message to the engineering squad notifying them of the new required field.