@@ -0,0 +1,13 @@
+---
+'@objectstack/plugin-audit': patch
+'@objectstack/metadata-protocol': patch
+---
+
+feat(audit): a package uninstall writes one `package_uninstall` row about the package itself
+
+Clause-②: yes
+Metadata-protocol: none
+
+Uninstalling a package left a `sys_audit_log` row for each metadata item it removed, and nothing about the package: its `sys_packages` row is deleted with raw SQL, so no hook ever saw it. A package that shipped no stored metadata left no trace at all. The uninstall verb (`deletePackage`, the path `DELETE /api/v1/packages/:id`, the import rollback, the paired-customization undo and any in-process caller take) now writes one row per package it uninstalled, after the package's stored row is gone: `action: "package_uninstall"`, the actor the verb was called for (`user_id` and `actor`; a `svc:` principal is the `actor` only), no record and no organization (an uninstall is environment-wide, so the row is deployment-level and served to the platform administrator alone), and in `metadata` the package id, its installed version, the environment, whether the object tables were kept, the items removed and left behind, and `outcome` (`complete` or `partial`).
+
+An uninstall the verb refuses writes no row, and neither does an id that is not installed. The writer lives on the `audit` service slot as `recordPackageLifecycleEvent`, beside `recordAuthEvent`; a kernel without the audit plugin uninstalls exactly as before, and a ledger write that fails is logged at `error` once per cause without changing the uninstall's answer.
@@ -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 **56 of the 269 sites are spelled that way**. A
+forwarding shim cannot, and **56 of the 270 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 | **269** |
+| 175 write call sites | quoted in the merged changeset | **270** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **30** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **191 of 269** decidable, **78** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 149 decidably elevated, 0 decidably not, 112 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **192 of 270** decidable, **78** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 150 decidably elevated, 0 decidably not, 112 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
-149 of 269 (55%) as decidably elevated, with 112 more whose elevation is a
+150 of 270 (56%) as decidably elevated, with 112 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 / 269`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 270`, 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" — **30 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 | **269** |
-| …whose object name is statically decidable | 191 |
+| write call sites on the application surface | **270** |
+| …whose object name is statically decidable | 192 |
 | …whose object name is chosen at run time | 78 |
-| …against an object with tenancy ENABLED | 185 |
+| …against an object with tenancy ENABLED | 186 |
 | …against an object that declares tenancy off | 6 |
-| threading a tenant context | 205 |
+| threading a tenant context | 206 |
 | 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 | 56 |
 | …of those, against a decidably tenancy-enabled object | 30 |
-| threading a decidably ELEVATED (`isSystem`) context | 149 |
+| threading a decidably ELEVATED (`isSystem`) context | 150 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 112 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 205 |
+| receiver carried a readable engine type | 206 |
 | receiver erased, placed by the object NAME | 54 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 122 |
+| object name spelled inline | 123 |
 | object name spelled through a `const` | 69 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 71 |
@@ -307,13 +307,13 @@ 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-07 at `a06983b5c`.
+Measured on 2026-11-07 at `9dd4abeaa`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 1052 |
+| tracked non-test sources scanned | 1057 |
 | engine-shaped types recognised | 113 |
 | declared objects in the registry | 131 |
-| same-named calls subtracted as non-engine | 237 |
+| same-named calls subtracted as non-engine | 239 |
 
 {/* END GENERATED: tenant-audit-census */}
@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 269 |
-| Object name statically decidable | 191 |
+| Write call sites | 270 |
+| Object name statically decidable | 192 |
 | Object name chosen at run time | 78 |
-| Against a tenancy-enabled object | 185 |
+| Against a tenancy-enabled object | 186 |
 | Against an object declaring tenancy off | 6 |
-| Threading a tenant context | 205 |
+| Threading a tenant context | 206 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 56 |
 | …and decidably tenancy-enabled | 30 |
-| Threading a decidably elevated context | 149 |
+| Threading a decidably elevated context | 150 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 112 |
 
@@ -90,14 +90,14 @@ 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-07 at `a06983b5c`.
+Measured on 2026-11-07 at `9dd4abeaa`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 1052 |
+| tracked non-test sources scanned | 1057 |
 | engine-shaped types recognised | 113 |
 | declared objects in the registry | 131 |
-| same-named calls subtracted as non-engine | 237 |
+| same-named calls subtracted as non-engine | 239 |
 
 ## Every site
 
@@ -123,6 +123,7 @@ Measured on 2026-11-07 at `a06983b5c`.
 | `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/package-lifecycle-audit.ts` | `insert` | `sys_audit_log` | enabled | elevated | 1 |
 | `packages/plugins/plugin-audit/src/read-audit.ts` | `insert` | `sys_audit_log` | enabled | options unreadable | 1 |
 | `packages/plugins/plugin-audit/src/stored-metadata-body-migration.ts` | `update` | `object` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-auth/src/admin-import-users.ts` | `insert` | `sys_audit_log` | enabled | options unreadable | 1 |
 
@@ -46,6 +46,12 @@ import { canonicalMetaType, captureUninstallDeclared, metadataReadFailureError,
 export interface PackageUninstallHost {
     readonly deleteMetaItem: ObjectStackProtocolImplementation['deleteMetaItem'];
     readonly engine: ObjectStackProtocolImplementation['engine'];
+    /**
+     * [#31186] The environment the protocol is bound to. The class field is
+     * private, so it cannot be named by an indexed access; it is read for the
+     * package's ledger row and nothing else.
+     */
+    readonly environmentId: string | undefined;
     readonly findEnvironmentRows: ObjectStackProtocolImplementation['findEnvironmentRows'];
     readonly getServicesRegistry: ObjectStackProtocolImplementation['getServicesRegistry'];
     readonly packagelessAddress: ObjectStackProtocolImplementation['packagelessAddress'];
@@ -54,7 +60,7 @@ export interface PackageUninstallHost {
 }
 
 /** The body of `ObjectStackProtocolImplementation#deletePackage`; the method's docblock there is its contract. */
-export async function deletePackage(this: Pick<PackageUninstallHost, 'deleteMetaItem' | 'engine' | 'findEnvironmentRows' | 'getServicesRegistry' | 'packagelessAddress' | 'runUninstallCleanups' | 'shouldDropStorage'>, request: DeletePackageRequest): Promise<DeletePackageResponse> {
+export async function deletePackage(this: Pick<PackageUninstallHost, 'deleteMetaItem' | 'engine' | 'environmentId' | 'findEnvironmentRows' | 'getServicesRegistry' | 'packagelessAddress' | 'runUninstallCleanups' | 'shouldDropStorage'>, request: DeletePackageRequest): Promise<DeletePackageResponse> {
     // [ADR-0131 D6/D12] An uninstall is environment-wide by construction:
     // every `sys_metadata` row bound to the package, in this environment,
     // whatever organization a legacy row was stored under. The
@@ -332,6 +338,10 @@ export async function deletePackage(this: Pick<PackageUninstallHost, 'deleteMeta
     // time: it is logged, not fatal, because the durable row is already
     // gone and the next boot is clean either way.
     //
+    // [#31186] What the registry holds for this id, read before the withdrawal
+    // below releases it: whether there was a package to uninstall, and its
+    // version, for the package's own ledger row at the end of this verb.
+    const installed = readInstalledPackage((this.engine as any)?.registry, request.packageId);
     // [ADR-0090 D5] What the package declared is captured first: the
     // withdrawal releases its names, and the cleanups below revoke the
     // grants that name them.
@@ -354,6 +364,24 @@ export async function deletePackage(this: Pick<PackageUninstallHost, 'deleteMeta
     // uninstall door calls too.
     const cleanups = await this.runUninstallCleanups({ ...request, ...(declared ? { declared } : {}) });
 
+    // [#31186] The package's own ledger row, written once, here, after its
+    // stored row is gone — the one place every uninstall door passes. A
+    // refusal above threw before this line, so it writes none. An id the
+    // registry did not hold and the store bound no metadata to was not a
+    // package, so it writes none either: the `DELETE` door answers that `404`.
+    if (installed.held || deleted.length > 0 || failed.length > 0) {
+        await recordPackageUninstall(this.getServicesRegistry?.()?.get('audit'), {
+            action: 'package_uninstall',
+            packageId: request.packageId,
+            ...(installed.version ? { version: installed.version } : {}),
+            ...(this.environmentId ? { environmentId: this.environmentId } : {}),
+            ...(request.actor ? { actor: request.actor } : {}),
+            ...(request.keepData === true ? { keepData: true } : {}),
+            itemsRemoved: deleted.length,
+            itemsFailed: failed.length,
+        });
+    }
+
     return {
         success: failed.length === 0 && deleted.length > 0,
         deletedCount: deleted.length,
@@ -363,3 +391,61 @@ export async function deletePackage(this: Pick<PackageUninstallHost, 'deleteMeta
         cleanups,
     };
 }
+
+/**
+ * [#31186] The event the uninstall verb hands the `audit` slot's
+ * `recordPackageLifecycleEvent` — declared here, structurally, so this package
+ * does not depend on `@objectstack/plugin-audit`, which owns the row shape
+ * (`package-lifecycle-audit.ts` there).
+ */
+export interface PackageUninstallAuditEvent {
+    action: 'package_uninstall';
+    packageId: string;
+    version?: string;
+    environmentId?: string;
+    actor?: string;
+    keepData?: boolean;
+    itemsRemoved: number;
+    itemsFailed: number;
+}
+
+/** The `audit` slot member the verb calls. */
+interface PackageLifecycleAuditSurface {
+    recordPackageLifecycleEvent?(event: PackageUninstallAuditEvent): unknown;
+}
+
+/** Whether the registry holds `packageId`, and the version it holds. Never throws. */
+function readInstalledPackage(registry: unknown, packageId: string): { held: boolean; version?: string } {
+    try {
+        const pkg = (registry as { getPackage?(id: string): unknown } | undefined)?.getPackage?.(packageId) as
+            | { manifest?: { version?: unknown } }
+            | undefined;
+        if (pkg === undefined || pkg === null) return { held: false };
+        const version = pkg.manifest?.version;
+        return { held: true, ...(typeof version === 'string' && version !== '' ? { version } : {}) };
+    } catch {
+        // A registry that cannot answer is not asked again: the row is then
+        // written only when stored items were removed, without a version.
+        return { held: false };
+    }
+}
+
+/**
+ * Hand the event to the `audit` slot. A host with no audit plugin has no
+ * ledger at all, so the call is skipped silently. The writer never throws; a
+ * slot that does anyway is a foreign writer, and the uninstall it reports on
+ * has already completed, so its failure is logged, never answered.
+ */
+async function recordPackageUninstall(audit: unknown, event: PackageUninstallAuditEvent): Promise<void> {
+    const record = (audit as PackageLifecycleAuditSurface | undefined)?.recordPackageLifecycleEvent;
+    if (typeof record !== 'function') return;
+    try {
+        await record.call(audit, event);
+    } catch (e) {
+        console.error(
+            `[protocol.deletePackage] '${event.packageId}' was uninstalled, but the audit service refused its `
+            + '`package_uninstall` row, so the compliance ledger does not record who uninstalled it: '
+            + `${(e as Error)?.message ?? String(e)}`,
+        );
+    }
+}