feat(audit): every data export writes one run-level sys_audit_log row, and the export action comes back with its writer

.changeset/30955-data-export-audit-row.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/plugin-audit': patch
+'@objectstack/rest': patch
+---
+
+feat(audit): every data export writes one run-level `sys_audit_log` row, and the `export` action comes back with its writer
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+`GET /data/:object/export` used to leave the compliance ledger nothing to say: a user could download up to 50,000 rows of any object they may export, `sys_audit_log` included, and no row recorded who, what or how much. Each export the door streams now writes one row with `action: "export"`, the object, `record_id: null` and the exporter (user, actor, tenant, and the agent or impersonator when there is one). Its `metadata` carries the format, the row count, the effective and requested limit and whether the 50,000 cap clipped it, whether the file was truncated at the limit, a bounded summary of the filter (field names and operators, at most 32 terms, never a comparand), whether a search term narrowed it (never the term) and the outcome. An export whose read fails after the checks records `outcome: "failed"` with the status and machine code it answered.
+
+A request refused before anything is read (no export permission, a bad parameter, an unparseable filter) writes no row; neither does the import template. The row is written after the file is finished, so the audit write never changes or delays the download; a ledger write that fails is logged at `error` once per cause and the export is unaffected.
+
+`export` is declared again on `sys_audit_log.action` (it was retired under #8147 because nothing wrote it) and is shown by the `config_changes` list view beside `config_change` and `import`. The writer lives on the `audit` service slot as `recordDataExport`, beside `recordAuthEvent` and `recordActionInvocation`; a kernel without the audit plugin exports exactly as before.

content/docs/permissions/tenant-audit-census.mdx

@@ -132,7 +132,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **55 of the 264 sites are spelled that way**. A
+forwarding shim cannot, and **55 of the 265 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -197,10 +197,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **264** |
+| 175 write call sites | quoted in the merged changeset | **265** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **29** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **187 of 264** decidable, **77** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 147 decidably elevated, 0 decidably not, 109 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **188 of 265** decidable, **77** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 148 decidably elevated, 0 decidably not, 109 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -217,11 +217,11 @@ would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-147 of 264 (56%) as decidably elevated, with 109 more whose elevation is a
+148 of 265 (56%) as decidably elevated, with 109 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 264`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 265`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **29 further sites** have an options argument this
@@ -233,28 +233,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **264** |
-| …whose object name is statically decidable | 187 |
+| write call sites on the application surface | **265** |
+| …whose object name is statically decidable | 188 |
 | …whose object name is chosen at run time | 77 |
-| …against an object with tenancy ENABLED | 181 |
+| …against an object with tenancy ENABLED | 182 |
 | …against an object that declares tenancy off | 6 |
-| threading a tenant context | 201 |
+| threading a tenant context | 202 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 55 |
 | …of those, against a decidably tenancy-enabled object | 29 |
-| threading a decidably ELEVATED (`isSystem`) context | 147 |
+| threading a decidably ELEVATED (`isSystem`) context | 148 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 109 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 202 |
+| receiver carried a readable engine type | 203 |
 | receiver erased, placed by the object NAME | 52 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 118 |
+| object name spelled inline | 119 |
 | object name spelled through a `const` | 69 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 70 |
@@ -307,11 +307,11 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-11-06 at `19cadde19`.
+Measured on 2026-11-06 at `4addb47fd`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 1044 |
+| tracked non-test sources scanned | 1045 |
 | engine-shaped types recognised | 112 |
 | declared objects in the registry | 130 |
 | same-named calls subtracted as non-engine | 234 |

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 264 |
-| Object name statically decidable | 187 |
+| Write call sites | 265 |
+| Object name statically decidable | 188 |
 | Object name chosen at run time | 77 |
-| Against a tenancy-enabled object | 181 |
+| Against a tenancy-enabled object | 182 |
 | Against an object declaring tenancy off | 6 |
-| Threading a tenant context | 201 |
+| Threading a tenant context | 202 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 55 |
 | …and decidably tenancy-enabled | 29 |
-| Threading a decidably elevated context | 147 |
+| Threading a decidably elevated context | 148 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 109 |
 
@@ -90,11 +90,11 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-11-06 at `19cadde19`.
+Measured on 2026-11-06 at `4addb47fd`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 1044 |
+| tracked non-test sources scanned | 1045 |
 | engine-shaped types recognised | 112 |
 | declared objects in the registry | 130 |
 | same-named calls subtracted as non-engine | 234 |
@@ -120,6 +120,7 @@ Measured on 2026-11-06 at `19cadde19`.
 | `packages/plugins/plugin-audit/src/activity-changed-fields-backfill.ts` | `update` | `sys_activity` | enabled | elevated | 1 |
 | `packages/plugins/plugin-audit/src/auth-event-audit.ts` | `insert` | `sys_audit_log` | enabled | options unreadable | 1 |
 | `packages/plugins/plugin-audit/src/comment-parent-pair-backfill.ts` | `update` | `sys_comment` | enabled | elevated | 1 |
+| `packages/plugins/plugin-audit/src/data-export-audit.ts` | `insert` | `sys_audit_log` | enabled | elevated | 1 |
 | `packages/plugins/plugin-audit/src/mail-log-body-migration.ts` | `update` | `object` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-audit/src/mail-log-body-migration.ts` | `update` | `object` | undecidable | options unreadable | 1 |
 | `packages/plugins/plugin-audit/src/read-audit.ts` | `insert` | `sys_audit_log` | enabled | options unreadable | 1 |

packages/plugins/plugin-audit/src/audit-plugin.ts

@@ -30,6 +30,7 @@ import { installAuditWriters, type AuditI18nSurface, type MessagingEmitSurface }
 import { installReadAuditWriter, type ReadAuditWriterHandle } from './read-audit.js';
 import { createAuthEventAuditSink } from './auth-event-audit.js';
 import { createActionInvocationAuditWriter } from './action-invocation-audit.js';
+import { createDataExportAuditWriter } from './data-export-audit.js';
 import { installCommentAccessHooks, installCommentReadVisibility } from './comment-access-hooks.js';
 import {
   COMMENT_REACTION_REMOVE_ROUTE,
@@ -320,6 +321,11 @@ export class AuditPlugin implements Plugin {
     // (`recordActionInvocation`): the two action doors in `@objectstack/runtime`
     // resolve it per request and hand it one event per invocation, naming the
     // door it came through (ruling 6513869839 on #27681, parameter 3).
+    //
+    // [#30955] And the data-export writer (`recordDataExport`): the REST
+    // export door resolves it per request and hands it one event per export
+    // it streamed, so every export of every object, this ledger included,
+    // leaves a run-level `export` row (`data-export-audit.ts`).
     const getLedgerEngine = (): IDataEngine | undefined => {
       try {
         return ctx.getService<IDataEngine>('objectql');
@@ -336,6 +342,7 @@ export class AuditPlugin implements Plugin {
     ctx.registerService('audit', {
       ...createAuthEventAuditSink({ getEngine: getLedgerEngine, logger: ctx.logger }),
       ...createActionInvocationAuditWriter({ getEngine: getLedgerEngine, logger: ctx.logger }),
+      ...createDataExportAuditWriter({ getEngine: getLedgerEngine, logger: ctx.logger }),
     });
 
     // ADR-0029 D8 — contribute this plugin's object translations to the i18n