docs(plugin-audit): the published README stops documenting an API, a row shape and an action vocabulary that do not exist (#9517) (#9531)

The README is in the package's published `files` array with `private` unset, so
it is what the npm package page renders. It documented twelve `auditService.*`
methods that exist nowhere in the repo, a `PluginAudit.configure({...})` entry
point that does not exist, an `IAuditService` spec contract that was never
declared, a row shape `sys_audit_log` does not have, action values outside its
enum, and six `/api/v1/audit/*` routes — all under a banner claiming SOC 2 /
HIPAA / GDPR readiness.

The compliance paragraph is deleted rather than softened or relocated: it is a
company-level claim needing an accountable owner, and does not belong in a
package README.

The replacement documents only what the code can be pointed at — the real
exports, the real columns, the seven-value action enum with the writer for each
value, the credential masking, and the subtract-an-exclusion-list coverage model.
It also states three gaps the old README obscured (reads, failed operations, and
the auth-events-only client fingerprint), and names two dependency boundaries
with their degraded behaviour per the access-recipes.mdx pattern.

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

.changeset/plugin-audit-readme-published-claims.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/plugin-audit": patch
+---
+
+docs(plugin-audit): the published README stops documenting an `auditService` API, a row shape and an action vocabulary that do not exist (#9517)
+
+<!-- adr-0087: not-required (no-migration-prescription) Documentation only. No
+authorable property is added, renamed, retired or tombstoned; no schema, type or
+runtime behaviour changes. The only edited artifact is the package README, which
+ships in the package's `files` array. -->
+
+`packages/plugins/plugin-audit/README.md` is in the package's published `files`
+array and `private` is unset, so it is **what the npm package page renders**. It
+documented an API surface with no implementation anywhere in the repo, under a
+banner claiming SOC 2 / HIPAA / GDPR readiness.
+
+**Measured against `origin/main` before anything was rewritten**, and the drift
+was wider than the ledger of it:
+
+- **Every `auditService.*` method the README called is absent from the repo** —
+  `getFailedActions`, `logAdminAction`, `logDataAccess`, and also
+  `getRecordHistory`, `getUserActivity`, `searchLogs`, `getRecordSnapshot`,
+  `generateReport`, `archiveLogs`, `purgeLogs`, `logDataDeletion`,
+  `logDataExport`. Twelve methods, zero implementations. A reader following the
+  README wrote code that could not compile.
+- **`PluginAudit` does not exist**, and neither does the `.configure({...})`
+  static it was called through — no class in this repo exposes one. The export is
+  `AuditPlugin`, a `Plugin` class registered as `kernel.use(new AuditPlugin())`
+  and taking **no configuration at all**. The documented config object
+  (`trackObjects`, `trackFields`, `retentionDays`, `autoArchive`, `excludeUsers`,
+  `trackSystemEvents`) was fabricated in full.
+- **`IAuditService` is not in `@objectstack/spec/contracts`** — the README's
+  "Contract Implementation" section named an interface the spec has never
+  declared.
+- **The row shape was not the shipped one.** The README declared `timestamp`,
+  `userName`, `userEmail`, `recordName`, `changes`, `sessionId`, `status` and
+  `errorMessage`. `sys_audit_log` declares none of them.
+- **The action values were outside the enum.** `'insert'`, `'auth:login'`,
+  `'security:password_reset'`, `'workflow:approval'` and `'user_role_change'` are
+  not forms this object accepts; the namespaced-colon spelling never was one.
+- **The object name was wrong** — `audit_log`, not `sys_audit_log`.
+- **The REST namespace does not exist.** Six `/api/v1/audit/*` routes were
+  documented; the object declares `apiMethods: ['get', 'list']` and is read over
+  the ordinary object API.
+
+The compliance paragraph is **deleted, not softened or relocated**: a
+regulatory-readiness claim is a company-level statement needing an accountable
+owner, and it does not belong in a package README. The three external
+SOC 2 / GDPR / HIPAA links that existed only to support that framing are gone
+with it.
+
+The replacement documents only what the code can be pointed at: the real exports;
+the real `sys_audit_log` columns; the seven-value action enum **with the writer
+for each value**, so a reader can check any row of it; the credential masking on
+`old_value` / `new_value`; and the coverage model, which is
+**all objects minus an exclusion list** rather than the fabricated per-object
+`trackObjects` config — subtraction, because the object universe is open and an
+enumerated allow list would silently stop auditing everything registered after
+boot.
+
+Three things are now stated that the old README obscured, all of them gaps a
+reader could otherwise mistake for coverage:
+
+- **reads and views are not on the ledger** — no writer emits a read action;
+- **failed operations are not on the ledger** — there is no success/failure
+  column, and the writers fire only on `after*` events, i.e. only on operations
+  that succeeded, so `getFailedActions`-style "security monitoring" had no
+  mechanism behind it in the first place;
+- **`ip_address` / `user_agent` are populated on auth events only** — the
+  record-level writer does not stamp them, so a null client fingerprint on a CRUD
+  row does not mean the request had none.
+
+Two dependency boundaries are **named with their degraded behaviour** rather than
+left silent, following the `access-recipes.mdx` pattern: hierarchy-relative
+permission scopes need `@objectstack/security-enterprise` and **fail closed to
+`own`** without it, so a grant written to let managers read their reports' audit
+rows shows them only their own on an open build; and `lifecycle.archive` needs a
+registered `archive` datasource, **failing closed to retention** without one —
+nothing is ever deleted and the table grows, which is the safe direction for a
+ledger but not the documented one.